PEP 287: reStructuredText Standard Docstring Format
Richard Jones
rjones at ekit-inc.com
Wed Apr 3 02:01:59 EST 2002
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
More information about the Python-list
mailing list