[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[David Goodger]

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