PEP 287: reStructuredText Standard Docstring Format

[Richard Jones]

On Wed, 3 Apr 2002 18:01, Paul Rubin wrote:
> 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.
> >
> > 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?
>
> I'm not sure.  The PEP examines a bunch of different markup-based
> alternatives rather than comparing markup vs. non-markup.  The problem
> it finds with Javadoc source isn't that it's merely non-beautiful, but
> that it's actually quite hard to read without practice and HTML
> familiarity.  So I don't see it as a matter of a markup vs. a
> non-markup camp.  If there were a markup system that was easier to
> read directly, that might be a better answer than either Javadoc or
> ReST.  I'm pretty comfortable with Texinfo, for example.

How I see it is that ReST is a middle ground between markup and non-. It has 
markup, and you can use it to the extreme. Or you can follow some simple 
conventions (the most basic form of markup) and not worry about all the finer 
detail stuff. The difference between::

   @section{The Section Title}

and::

   The Section Title
   -----------------

Is pretty clearly to me that the second doesn't _look_ like markup, even 
though it is. It looks more like a convention (and a fairly common one, when 
you let the '-------' be any non-alphanum character).


> > > >    .. contents:: **Table of Contents**
> >
> > 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 :)
>
> You might also want to add a directive for enumerated lists, so that
> if you insert a new item in the numbered list in your Roundup docs,
> you don't have to manually renumber the rest of them.
> [and some more extreme examples]

I don't believe that's what directives are _for_. They're used to perform 
tasks that can't reasonably be performed by simple markup. Embedding images, 
automatically scraping the document for a table of contents, defining a 
reference to an external document... But not for creating tables - there's a 
reasonable way to do that with simple markup. Well, that's how I see it, 
anyway :)


> That will help, but I thought the idea of a PEP was to present a complete
> specification of the proposed feature, which is why I didn't follow the
> external references too carefully.

I think the problem is that the ReST and greater DPS specifications are 
simply far too big to include in the PEP, so David's summarised what he 
thought were the pertinent points out of that large volume. I thought he'd 
done a pretty good job :)


> Btw, could those responding to me please just respond here in the
> newsgroup-- I don't need the email carbon copies since I'm reading
> here.  Thanks.

My apologies - I'll stop :)

Actually, that's it for me tonight - I gotta go. I'll read the thread 
tomorrow with interest :)


    Richard