[Zope-dev] Re: Future of StructuredText

[David Goodger]

Simon Michael wrote:
>>> My two cents - there are some things in rST I would like to have but I
>>> think it has gone too far with it's rules.

Richard Jones wrote:
>> This seems to be a common argument, and I honestly can't understand it. I'm
>> not going argue it here, I'll just point you all to the "primer" document
>> which outlines the basics of ReST:
>> 
>> http://docutils.sourceforge.net/docs/rst/quickstart.html
> 
> Hi Richard,
> 
> It was more an expression of personal taste than an argument.  But I
> didn't understand your not understanding,

I believe Richard is referring to a phenomenon I've experienced as well
(although it's probably not what Simon initially complained about, which was
in fact the *PEP* rules).  Newbies will read through the reStructuredText
spec and gasp, "Too many details!  Too many rules!  Too complex!", followed
by, "Not for me!".  Thanks to Richard, we now have the Primer document
referenced above.  I've just added a note to the beginning of the spec,
basically saying "New Users: read the Primer first!"

There are also the people who complain that reStructuredText is "too
complex", referring to the number of constructs available.  It's not
complex; it's rich.  To the new user, the constructs listed in the Primer
above are sufficient.  But when the user has need for more sophisticated
constructs, they're ready & waiting.  Other markups, like StructuredText,
are much more limited; they reveal their limitations when the user needs
more than a really simple "toy" markup.  reStructuredText aims for a higher
level of completeness and flexibility.  Of course, there are limits inherent
in the premise of readable plaintext, and there are applications for which
these limits rule out the use of reStructuredText.  But reStructuredText
pushes the envelope, allowing for a lot more without resorting to verbose,
ugly, unreadable XML-type markup.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/