PEP 287: reStructuredText Standard Docstring Format

[Richard Jones]

On Wed, 3 Apr 2002 09:37, 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.

Are you speaking from experience of using the "markup" (which tends to be 
extremely unobtrisuve) or are you just bashing? Given that 'single' and 
"double" quoting have no effect? And :colons: aren't used for general 
document quoting, but rather structural information? And that `backquoting` 
generally won't be used in most documents?

For a _practical_ example of the "markup", please see the Roundup 
documentation mentioned in my response. I think you'll find that the original 
text is perfectly readable and significantly easier to edit and maintain that 
any "explicit" markup language. Apologies for the long 
  
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/roundup/roundup/doc/installation.txt?rev=HEAD

Note that my manual Table of Contents at the top is now possible using a 
directive::

   .. contents:: **Table of Contents**

The output is at http://roundup.sf.net/doc/installation.html


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

Javadoc. Bleah. Completely unreadable in its source form - which is in the 
code. You need to be able to read the documentation when viewing the code!


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

Please, read the justification text, and the anlysis of existing formats. 
POD, while not mentioned, shares a lot of the shortcomings of other STX 
formats in that it was grown over time.


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

Again, have you _read_ the ReST documentation, specifically the discussion of 
alternatives? It's extensive, and very well written. It discusses many 
existing STX systems and their strengths and weaknesses.


>  Javadoc and POD are
> widely-deployed, practical systems; a lot of people use them and like
> them and there are REASONS for that.

They are defacto standards. That's not always the sign of a well-designed 
system.


     Richard