PEP 287: reStructuredText Standard Docstring Format

[Paul Rubin]

David Goodger <goodger at users.sourceforge.net> writes:
> Here's a serious proposal, safe to post now that April Fool's is over.
> Please read & comment.

Man, I thought it was an April fools joke when I saw it last night.
All those `different` :kinds: 'of' "quoting" are much more confusing
than explicit markup.  So I think it's better to use explicit markup.
The ultimate explicit system is tangle/weave but that's a bit extreme.
Javadoc has been very successful in practice and you could do a lot
worse than just copying it lock stock and barrel.

The reStructuredText stuff looks like POD all over again.  If you want
POD, I'd say just use POD, rather than coming up with yet another
incompatible format.

The thing I like least about the PEP is that it's written like
marketing material--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.  Javadoc and POD are
widely-deployed, practical systems; a lot of people use them and like
them and there are REASONS for that.  The PEP should acknowledge their
success and see if there's something to be learned from it, rather
than dismissing them so airily.

Finally, among the explicit markup languages examined in the PEP,
Texinfo should be included.  It's much less ugly than html/sgml, and
its markup commands are directly designed for documentation rather
than typesetting.  I think it answers the criticisms made of the other
explicit markup systems mentioned, maybe not totally, but at least
partially.