ANN: New PEP Format: reStructuredText

[Terry Hancock]

> From: mlh at furu.idi.ntnu.no (Magnus Lie Hetland)
> In article <mailman.1030796387.5329.python-list at python.org>, Richard
> Jones wrote:
> >On Sat, 31 Aug 2002 9:44 pm, Magnus Lie Hetland wrote:
> >> In article <0z+c7LA8mHc9EwYa at jessikat.fsnet.co.uk>, Robin Becker wrote:
> >> [snip]
> [snip]
> >> - Magnus (who finds reStructuredText to be much more complicated than
> >>   XML)
> >
> >How on earth is this: [...] more complex than this... [...] 
> > .. can't see it myself... :)
> 
> Heh. Well, without getting into an argument over this, I can try to
> explain what I mean.
> 
> reStructuredText (as opposed to StructuredText and several other
> simpler formats) has lots of syntactic rules for various special
> cases. XML has the following rules (more or less):
>   [...]
> A given document format can then list what tags are allowed etc.
> 
> To me, this is very simple.
> 
> 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.

I already found Structured Text to be pushing the limits
of sensibility (so I suspect reStructuredText to be beyond
it). The thing is, that I see Structured Text as basically
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. Even adding a few useful conventions
is helpful.

Such an unstructured approach to design, is however,
more limited in its scope.  As you add more tricks to
it, I have to remember more of them. Also, there's no
easy way to find what I want (doesn't matter now because
the list is still short -- but it had better stay that
way if you want it to remain useful).  You might say
that it takes up space in my head in a linear way --
I need to remember N things to do N things.

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 may take up more space on disk, but it
takes a lot less space in my head to remember how it
works (I only have to remember a key to a generalized
set of tasks, followed by a key to a particular subtask,
etc -- so it's more like log N things to remember to
do N things? ;-D). This is because it's easy to look
up tags if I can't remember them -- this is not true
of obscure symbols and "idioms".  XML continues to
be useful even for arbitrarily complex markups.

XML pays a penalty for this on the small side, though:
As Robin indicated by example, even for trivial cases,
you need a fair amount of markup.

Structured Text is simple if-and-only-if the markup it
represents is simple (but then it can be even simpler
than XML).

As a substitute for plain text, I find Structured
Text to be very useful (e.g. I can put links to my primary
documentation in my docstrings. Cool!).  I'm also planning
to use Structured Text instead of "BB Code" for forum
posts (actually I'm using filtered HTML now, which is *lame*
for everyday posting use -- but useful if you want it to
look "just so").

So, I think they both have applications -- however I
would assert that the attempt to extend structured
text to handle generalized markup is a bit misguided.
Minimalism can be a good thing.

Cheers,
Terry

-- 
------------------------------------------------------
Terry Hancock
hancock at anansispaceworks.com       
Anansi Spaceworks                 
http://www.anansispaceworks.com 
P.O. Box 60583                     
Pasadena, CA 91116-6583
------------------------------------------------------