PEP 287: reStructuredText Standard Docstring Format

[Peter Hansen]

Paul Rubin wrote:
> 
> 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.

I had the same impression.  I was reading it for the first time,
as I showed it to a coworker who was interested.  By the time we'd
scrolled through the ReStructured Text documentation I had to say
to him, "Hmm... that's so bloody complicated it might be easier
writing XML tags directly.  Sort of defeats the purpose of structured
text, doesn't it?"

When structured text becomes so complicated to type that one has to
actually work at it, and it needs a large manual to use, it has
become too unwieldy to be useful.

My suggestion would be go with a simpler Structured Text for the 80%
of documentation needs it, and allow an escape to DocBook or 
something for more complicated docs...

-Peter