[Python-Dev] [Doc-SIG] that library reference, again

[David Goodger]

[David Goodger]
>> The second sentence lacks a rationale.  What's wrong with "--
>> dashes"?  What's "silly" about "``quotes''"?

[Fredrik Lundh]
> don't you know *anything* about typography ?

Yes, for a layman, I know plenty.  I am not a typographer though.

Simply put, your "list of goals" provides no context for your
statements.  *I* know that "--" is turned into an en-dash in TeX, and
that "``these''" are turned into curly quotes.  So?  What's "silly"
about that?  Spell it out, man!  And what about 99% of the people who
read your page?  They won't know the first thing about what you're
talking about.

>> The reference to ReST is wrong here; ReST certainly can know the
>> semantics of a given identifier.
>
>> I don't think you understand ReST except superficially.
>
> That's why I'm listening to people who've tried to use ReST for this
> purpose.  They've all failed.  Maybe they also only understood ReST
> superficially.

Perhaps, since ReST is *not* designed as a semantic markup language.
It's designed as an implicit markup language, with explicit extensions
for semantic markup.  In any case, ReST is *not* being proposed here.

> Or maybe it's because ReST is created by people who have a very
> shallow understanding of the issues involved in writing structured
> reference documentation.  Your guess is as good as mine.

Why does Fredrik find it necessary to descend to personal insults?
Your guess is as good as mine.

> Support for quick turnaround, edit via the web, richer semantic
> information, and a larger existing toolbase isn't better than the
> status quo ?

Those would be good features.  Those features are not mentioned in
your list of goals though!  (http://effbot.org/zone/pythondoc-lib.htm)
AFAICT, you just went off on a tangent to create a new markup
language, which we don't need.

> The problem is that the WORKFLOW doesn't work.

So fix the workflow.  Something like Ian Bicking's Commentary system,
or something more specific to Python's docs, seems to fit the bill.

> It's the workflow that's the real problem here, but you cannot fix
> the workflow without fixing the markup.

I disagree.  The markup doesn't need an overhaul to fix the workflow.

> I assume this means that we're going to keep getting more "ReST can
> certainly do this but we're not going to show anyone how" posts from
> the ReST camp ?

You assume incorrectly.  I'm not talking about ReST.  I'm not
proposing ReST for anything.  Please ignore the fact that I'm the
author of ReST; I never brought it up, I never proposed it.  *You* are
the one harping on it.

I'm just against an arbitrary and unnecessary change of markup in
Python's docs.

> Your reply makes it obvious that you don't understand the issues
> involved here, nor how the goals address them.

Your reply, and your regular descent to personal insults, make it
excruciatingly obvious that you're a troll.

I hesitated before first replying to this thread, suspecting (from
past experience) that this would be the response I'd get.  From now
on, I'll avoid feeding this particular troll.

> I'd say that the fact that you're asking this should disqualify you
> from ever working on documentation tools again...

Your writing malicious crap like this ought to disqualify you from
ever participating in python-dev discussions again.

Fredrik, we all know that you you are a superb developer who makes
wonderful contributions to Python.  We also know that when faced with
disagreement (and sometimes, seemingly, without any provocation at
all) you are a malicious prick.

-- 
David Goodger <http://python.net/~goodger>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 249 bytes
Desc: OpenPGP digital signature
Url : http://mail.python.org/pipermail/python-dev/attachments/20051230/b6af558a/signature.pgp