Fredrik Lundh wrote:
the first time, I got to the following complete nonsense:
"XML and SGML /.../ are verbose, difficult to type, and too cluttered to read comfortably as source."
and having written several books in SGML and XML without noticing any of those "widely known" problems, I decided that it wasn't meaningful to continue.
Your ellipsis omits all the good things I said about XML/SGML. The rest of the quote is supposed to be read in the context of: 3. Explicit markup (like XML or TeX) is widely considered unreadable by the uninitiated. Where "by the uninitiated" is key. Having written books in SGML/XML, written the "sre" engine, and made many other wonderful contributions, you are obviously not among the uninitiated. I'll make that more explicit.
I've never seen such an arrogant PEP before
Is this intentional flamebait? Pot calling the kettle black? I will try to restrain myself. ;-)
the authors clearly have very little experience from the problem domain (not only writing and maintaining documentation with markup, but also what makes Python so incredibly usable),
You are mistaken. Personally, I have over six years of experience with SGML & XML, doing document analysis, writing DTDs, and writing document processing systems, for English, Japanese, Chinese, and Korean data. Four years of experience with Python. Member of the Doc-SIG for two years, but I've read over much of the six-year archive. I still have much to learn, no doubt. If you can point out any specific areas where the PEP is lacking with regards to the above, I'd be happy to do the research.
yet they want to want to force their new invention down everyone's throat (hey, we spent a lot of time desiging this, so of course you shall have to use it)
Perhaps you missed the second paragraph of the Abstract? [This PEP is not] an attempt to deprecate pure plaintext docstrings, which are always going to be legitimate. The reStructuredText markup is an alternative for those who want more expressive docstrings.
want to contribute a PEP? sorry, you have to learn a new markup language.
The current standard could easily coexist with the proposed. Whether or not to use the new markup could be left to PEP authors, or decreed. That's a policy decision.
want to fix something in the README? sorry, you have to learn a new markup language. want to fix a module in the standard library? sorry, you have to learn a new markup language. it's easy.
How about: "Want to add to Python's standard documentation? Sorry, you have to learn a new markup language: TeX." Same thing. But hacking on reStructuredText is much easier than hacking on TeX. In any case, there is no *requirement* to use reStructuredText. If the PEP is accepted, it becomes *a* standard for docstrings, but not *the only* standard. At minimum, plaintext docstrings will remain.
there are only a couple of 100ks of specifications to read and understand.
There's need for a short user introduction, true. I apologize that it wasn't already in place. The beginnings of such an introduction is at http://structuredtext.sourceforge.net/docs/quickstart.txt. This is the first time I've seen a proposal blasted for having *too much* documentation! ;-) How many Python programmers read the entire Language Reference, let alone the Library Reference? Few, I imagine. So what? Heck, had I been told I had to read O'Reilly's "Python Standard Library" cover to cover before I could write my first line of code, I probably never would have begun.
(and while you're at it, get a new keyboard; we don't care much about people using non-US keyboards...)
Can you be specific?
-1. the world doesn't need another markup language. there is only one markup language that everyone knows, and it's called HTML. the javadoc folks got it right. this one's all wrong.
You don't like it, fine. I don't see much substantive in your posts here or on comp.lang.python; paraphrased, you're saying "this sucks". Care to give any reasoning behind your conclusion? I must have stepped on some sensitive toes to warrant such a reaction! -- David Goodger goodger@users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net