PEP 287: reStructuredText Standard Docstring Format

[Paul Rubin]

Richard Jones <rjones at ekit-inc.com> writes:

> 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

That looks pretty similar to an Info file (texinfo output).  I think
I'd rather type "@section{Overview}" than have to supply those special
underscores directly.

> 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 the ink isn't even dry on this PEP and already it's sliding down
the slippery slope into explicit markup <wink>.

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

I don't find Javadoc unreadable (it's just HTML) but it's certainly
ugly and I'd rather read a formatted version.

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

I did read the justification text but found it scanty and
unpersuasive.  It read too much like a sales pitch and not enough like
an objective analysis.

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

I looked briefly at the ReST documentation linked from the PEP, but
if I'm supposed to read it in detail to be able to use it, I might
as well use a more traditional markup language.

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

They have good and bad points, and their good points were attractive
enough that a lot of people were willing to write docs in them instead
of in plain text or as separate docs rather than inline as is
traditional for C programs.  That says something in their favor.