PEP 287: reStructuredText Standard Docstring Format

[Delaney, Timothy]

From: Paul Rubin [mailto:phr-n2002a at nightsong.com]
> Richard Jones <rjones at ekit-inc.com> writes:
> 
> 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.

The whole point is that this is the *input*, optionally to produce another
format, and is also human-readable in the source code (or any other text
file). Your statement above simply supports the use of ReST, as its native
format is "pretty similar" to texinfo output, which you have stated
previously that you prefer to the texinfo source.

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

Huh? If you'd read the accompanying docs, you would know about the ReST
directives. I wouldn't call the .. contents:: directive "explicit markup"
considering that it inserts an entire table of contents with one short line
...

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

Exactly! With ReST you can read either the original version, or a formatted
version, and *neither* is ugly. In fact, while I was reading the
accompanying docs I preferred to read the text (ReST) version rather than
the HTML version.

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

Personally, I got lost a few times, but it was my first reading of the docs,
and there is a lot of information there.

> 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 looked briefly at the Python documentation linked from the web site, but
if I'm supposed to read it in detail to be able to use it, I might as well
use a more traditional programming language.

I don't think I need to say more.

Tim Delaney