PEP 287: reStructuredText Standard Docstring Format

[Richard Jones]

On Wed, 3 Apr 2002 16:46, Paul Rubin wrote:
> 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/instal
> >lation.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.

Yeah, I guess at this point it's down to personal preference. I think we can 
summarise by saying that you're happy to have your documentation source in 
the texinfo format [#]_, whereas the Structure Text camp would rather see it 
more looking like actual documentation. Is that fair?

. [#] or something else that's got "bearable" readability issues, where
      "bearable" is determined on an entirely personal scale :)


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

I think it's justifiable in this case - it saves a lot of typing :)

Also, the other commonly used explicit markup is images::

  .. image:: graphic.png

... that's pretty hard to do without an explicit markup (short of 
ASCII-art'ing the PNG :)



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

Fair enough, I thought it was pretty balanced. 


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

I've started writing a "primer" that should be the first port of call. It's a 
somewhat more verbose version of selected parts of the quick reference. Just 
the basics, explained in a little more detailed and human way than the formal 
documentation. I'd hope that that helps a little...



     Richard