Marketing reST (was Re: What YAML engine do you use?)

[Aahz]

In article <mailman.1039.1106341195.22381.python-list at python.org>,
Fredrik Lundh <fredrik at pythonware.com> wrote:
>
>I've read many specs; YAML (both the spec and the format) is easily
>among the worst ten-or-so specs I've ever seen.
>
>ReST and YAML share the same deep flaw: both formats are marketed as
>simple, readable formats, and at a first glance, they look simple and
>readable -- but in reality, they're messy as hell, and chances are
>that the thing you're looking at doesn't really mean what you think it
>means (unless you're the official ReST/YAML parser implementation).
>experienced designers know how to avoid that; the ReST/YAML designers
>don't even understand why they should.

While I can see how you'd get that impression of reST, it's not true:
like Python, reST is intended to be simpl*er* and readable, but not
simple.  The joy of reST is that I can concentrate on writing instead of
formatting, just as I do when writing Usenet posts.  ;-)  Even after
using reST for a long time, I'm still constantly looking up features that
I use rarely (such as correct formatting of URLs).

But reST is great because it's relatively unobtrusive.  Those of us
who've used reST to document code for a long time have gotten into the
habit of using some reST-isms even when not writing reST: have you
noticed the number of Pythonistas who use constructs like ``foo()``?
Even if you didn't know it was from reST, the meaning is obvious.

As you say, reST can/does get messy when you're doing complicated things,
but it stays more readable than XML/DocBook.  For the most part, I think
I'd also have to disagree with your assertion that reST formatting
doesn't do what you think it does.  In cases where your statement is
correct, it's either labeled as an explicit design decision (to prevent
other ugliness) or it's a bug.
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"19. A language that doesn't affect the way you think about programming,
is not worth knowing."  --Alan Perlis