PEP 287: reStructuredText Standard Docstring Format

[David Goodger]

Paul Rubin wrote:
> Man, I thought it was an April fools joke when I saw it last night.

That's why I explicitly stated that it *wasn't* one. :-)

> All those `different` :kinds: 'of' "quoting" are much more confusing
> than explicit markup. So I think it's better to use explicit markup.

Single and double quotes are *not* significant in reStructuredText,
for the simple reason that they're commonly used in ordinary text.

The markup constructs used by reStructuredText were chosen from common
usage or designed with the goal of being "as simple and unobtrusive as
possible".  In reStructuredText, readability is a much more important
goal than writability.

For computers, explicit markup is definitely easier to deal with.
Having written a parser for implicit markup, I'm painfully aware of
this.  But for untrained humans, explicit markup is very difficult to
read -- all the markup is very distracting.

> The thing I like least about the PEP is that it's written like
> marketing material

PEPs *are* marketing tools.  They market proposals to the Python user
community and PythonLabs, lobbying for support.  They must be
persuasive, both technically and expositorially.

> --it sets out to push a particular solution and looks for things to
> bash about the alternatives rather than treating them evenhandedly
> and being willing to accept the idea that reStructuredText may not
> be the answer.

The PEP briefly examines alternatives proposed in the past, on the
Doc-SIG, in terms of "the generally accepted goals for a docstring
format".  I think you're reading too much into the prose as it stands.

This PEP toots its own horn.  Why should it toot somebody else's?

> Finally, among the explicit markup languages examined in the PEP,
> Texinfo should be included.

Texinfo is not included because it has never been seriously proposed
as a docstring format [#]_.  Looking at samples, I can see why.

.. [#] If you care to propose Texinfo as a standard docstring format,
   please join the Doc-SIG, make your case there, then write a PEP.

The entire premise of this PEP and of the Doc-SIG's (at least) 6-year
docstring markup odyssey is that Pythonistas want a markup that is
"readable in source form".  We're spoiled by Guido's programming
language design aesthetics, and that spilled over into the docstring
markup debate.  Better late than never.

-- 
David Goodger    goodger at 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