ANN: New PEP Format: reStructuredText

[David Mertz, Ph.D.]

Magnus Lie Hetland wrote:
|> I like plain-text formats, but I reStructuredText is too convoluted
|> (and has too many strange constructs, like lots of underscores and
|> double colons etc) for my taste. I'm sure many others (among them, I'm
|> sure, the designers) will find it to be the perfect balance of
|> simplicity and functionality.

Terry Hancock <hancock at anansispaceworks.com> wrote previously:
|...a way to sense what an author intended in a plain text
|document. If it can figure out what was intended, using
|the simple tricks that have evolved in plain text email,
|that is a good thing.
|Actually I just looked up the spec -- this list isn't
|really short anymore, is it?
|Lots of special case knowledge is *not* better than a
|general, extensible framework which follows simple
|rules -- XML...

There certainly are contrary pulls here, huh?  I have had to worry about
the same issues in the stuff I do.  Many c.l.py readers will know me
from the articles I do.  Those are (almost) all composed in what I call
"smart ASCII".  As a format it is simpler than reStructuredText is,
while using a number of the same "intuitive" email-like conventions.  I
find it a heck of a lot easier to write articles this way than I would
using XML or HTML, or a proprietary wordprocessor and its format.  So I
think that format is at just the right level.  But even there, there are
a couple little picky rules that I need to obey (more so now that IBM dW
has gone to an XML intermediate format).

For my TPiP book, I decided to use the same format, and adjust the
conversion so it would go to LaTeX instead of XML/HTML.  This still
works pretty well, but as I worked on it, I found a number of little
nit-picky issues that couldn't quite be automated with the current
markup.  I went back to the format, and added some special meanings to a
few sequences of symbols, to touch up elements of spacing, pagination,
etc.  But this is my own internal thing...  I'd kinda hate to force
someone else to remember the same set of convoluted special symbols.

Of course, I don't think XML is any better...  I can remember a few
funny symbols more easily than I can 100 docbook elements and their
exact permitted nesting and sequencing rules.  XML in the abstract (i.e.
well-formed only) is simple, but once you get a dialect, it becomes a
pain.

The thing about smart ASCII (and its variants) and reStructuredText
also, is that while there are many rules to remember for the writer of
the format, it is extremely easy to READ.  You can look at my TPiP book
online, and you will not necessarily know why a line with just "+++"
occurs every once in a while... but you don't NEED to know.  The symbol
is quite unobtrusive, and just adds an extra little bit of vertical
space to the page.  The same thing goes for PEPs in reStructuredText.  I
really don't know exactly when dashes versus equals signs might occur
below or above a heading... but it doesn't particularly harm readability
to remain in the dark on this.  If I see a double colon every once in a
while, I might not know the exact semantics of when it is allowed, but
it also doesn't do much to the reading flow.

I think reStructuredText is just the right level of complexity for PEPs.
It imposes an extra burden on PEP writers, but that's not so bad.  It
doesn't hurt the readers of PEPs at all, and it makes conversion to
other formats automatic.

Yours, David...

--
 mertz@  _/_/_/_/ THIS MESSAGE WAS BROUGHT TO YOU BY: \_\_\_\_    n o
gnosis  _/_/             Postmodern Enterprises            \_\_
.cx    _/_/                                                 \_\_  d o
      _/_/_/ IN A WORLD W/O WALLS, THERE WOULD BE NO GATES \_\_\_ z e