[Doc-SIG] that library reference, again
David Goodger
goodger at python.org
Fri Dec 30 17:27:20 CET 2005
[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/doc-sig/attachments/20051230/b6af558a/signature.pgp
More information about the Doc-SIG
mailing list