[Python-Dev] [Doc-SIG] that library reference, again (original) (raw)

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/python-dev/attachments/20051230/b6af558a/signature.pgp

More information about the Python-Dev mailing list