[Python-Dev] Re: Docutils/reStructuredText is ready to process PEPs

[David Goodger]

Ka-Ping Yee wrote:
> I have just read the specification:
> 
>     http://docutils.sourceforge.net/spec/rst/reStructuredText.html
> 
> It took a long time.  Perhaps it seems not so big to others, but
> my personal opinion would be to recommend against this proposal
> until the specification fits in, say, 1000 lines and can be absorbed
> in ten minutes.

The specification is, as its title says, a *specification*.  It's a detailed
description of the markup, intended to guide the *developer* who is writing
a parser or other tool.  It's not user documentation.

For that, see the quick reference at
http://docutils.sf.net/docs/rst/quickref.html.  It's only 1153 lines of HTML
(with lots of blank lines and linebreaks, hand-written before the
reStructuredText parser could handle everything).

Perhaps you started at the wrong end.  The best place to start is with "A
ReStructuredText Primer" by Richard Jones, at
http://docutils.sf.net/docs/rst/quickstart.html (which *is* generated from
text).  It's only 335 lines long :-).  It leads to the quick reference,
which leads to the spec itself.

And there was this item of the "deployment plan":

    - Modify PEP 1 (PEP Purpose and Guidelines) and PEP 9 (Sample PEP
      Template) with the new formatting instructions.

PEP 9 could contain or point to a short & to-the-point overview of the
markup.  I see no problem coming up a user document that's more complete
than the "Primer" above but still weighs in at under 1000 lines.  But with
the docs mentioned above, it it necessary?

You could also begin by perusing an example.  Look at the markup in
http://docutils.sf.net/spec/pep-0287.txt, marked up in reStructuredText in
the intended way.  With the exception of embedded references and targets
(for which there is no plaintext equivalent), none of the markup there looks
like markup, and should be very easy to follow.  Now look at the processed
result (http://docutils.sf.net/spec/pep-0287.html); I think the return is
worth the investment.

> For me, it violates the fits-in-my-brain principle:
> the spec is 2500 lines long, and supports six different kinds of
> references and five different kinds of lists (even lists with roman
> numerals!).  It also violates the one-way-to-do-it principle:
> for example, there are a huge variety of ways to do headings,
> and two different syntaxes for drawing a table.

How many times have we heard this?  "All we need are paragraphs and bullet
lists."  That line of argument has been going on for at least six years, and
has hampered progress all along.

IMHO, variety in markup is good and necessary.  Artificially limiting the
markup makes for limited usefulness.

OTOH, I have no problem with mandating standard uses, like a standard set of
section title adornments.

> I am not against structured text processing systems in general.
...
> It's just that RST is much too big (for me).

Somehow I think that "size of the spec" is a specious argument.  Take the
Python spec, for example: many times the size of the reStructuredText spec
and yet it arguably fits in many different sized brains.  I know they're
different things and I'm not implying they're the same; the markup is a much
smaller thing.  reStructuredText is very practical in its scope.  Constructs
are there because they're useful and *used*.  If we removed all the items
you list, we'd end up with a crippled markup of little use to anyone.

> I think that something of this flavour would be a great solution
> for PEPs and docstrings, and that David has done an impressive
> job on RST.

Thank you.

Anyhow, off to work.  I'll follow up on further posts this evening.

-- 
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/