[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

Fredrik Lundh fredrik@pythonware.com
Wed, 3 Apr 2002 11:18:16 +0200

david wrote:

> Does a lack of responses mean that there *are* no issues?

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.


after a second attempt to read it, I got stuck in the Q&A
section.  I've never seen such an arrogant PEP before; 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),
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): want to contribute a
PEP?  sorry, you have to learn a new markup language.  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.
there are only a couple of 100ks of specifications to read and
understand.  (that's only slightly larger than the Ruby language
reference, and we're convinced that you'd rather learn another
markup language than another programming language, right?)

(and while you're at it, get a new keyboard; we don't care much
about people using non-US keyboards...)


-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.