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/