
[Ping]
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.
[David]
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.
[Ping]
Okay, i understand that it's a spec and not a user manual. I think the fact that it takes that much text to describe all of the rules does say something about its complexity, though.
I prefer the term "rich" over "complex". ;-) Seriously, any significant technology requires a significant spec. Did you look at the primer and quick reference? - Primer: http://docutils.sf.net/docs/rst/quickstart.html - Quick reference: http://docutils.sf.net/docs/rst/quickref.html I wouldn't recommend the Language or Library Reference to a Python newbie either; they're references! I'd point them to the Tutorial. The primer above is reStructuredText's tutorial: short & sweet.
But again i want to stress that i think the structured-text approach is good and i do not advocate abandoning the whole idea; i just want a simpler set of rules.
Speaking from experience having hashed out all these issues over the last two years, "a simpler set of rules" won't work. Sure, a few conveniences could be trimmed from reStructuredText, and all we'd lose would be convenience. Go past that and the markup would become less useful. Cut everything you listed and the markup would be next to useless.
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.
Well, that depends what you mean by "progress"! :) There might be something to that line of argument, if it has a habit of cropping up.
"Progress" in auto-documentation tools for Python. "Progress" in a usable, successful structured plaintext markup. OTOH, there's been just as much pressure from the other direction: "The markup needs a construct for XYZ." reStructuredText is the result of working toward a practical, usable, and readable balance.
One can separate two issues here:
1. too much functionality (YAGNI) 2. too many ways of expressing the same functionality (TMTOWTDI)
As for the first, there's some room to argue here. I happen to feel there are quite a few YAGNI features in RST, like the Roman numerals and the RCS keyword processing.
What's the big deal about Roman numerals? Human beings have many ways to count; our markup should allow us the freedom to choose the style we like. Ask a lawyer if Roman numerals for lists are expendible. If *you* don't like them, don't use them. RCS keyword processing is *not* a syntax feature; it's for readability, so readers don't have that $RCS: cruft$ shoved in their faces.
Auto-numbering in particular takes RST in a direction that makes me uncomfortable -- it means that RST now has the potential for a compile-debug cycle.
That's true with *any* markup processing system. It's the price of the increased functionality and readability of the processed result. A small price, IMHO. The reStructuredText parser is very helpful with diagnostics, and can only improve with user feedback. I've volunteered to do the processing, so there should be no impact on anyone.
But as for the second, i just don't see any justification for it. Reducing the multiple ways to do headers and lists and tables doesn't cripple anything; it only makes RST simpler and easier to understand.
Headers: by "multiple ways", are you referring to the author's choice of underline style? Or to the choice for overline & underline versus underline-only? Perhaps, when reading the spec, it's overwhelming; so don't start with the spec! But I don't see the big deal in having variety. The true test is this: when you look at a reStructuredText title, in whatever style, does it scream out at you, "I am a title!"? Without knowing anything about the markup, most people would answer "yes, it does". The same is true for lists and tables too. I base this on reports from people who are using Docutils/reStructuredText in the real world, introducing it to non-technical users, and reporting nothing but positive experiences. Lists: see below. Tables: the "simple table" syntax was added recently, because although it's limited, it's much simpler to type and edit than the original "grid tables". But grid tables don't have the limitations, so it's practical to keep both constructs around.
I acknowledge that there is some question of opinion as to what is the "same" functionality, causing issues to slush over from #1 to #2.
To me, using "1.", "(1)", or "1)" to number a list makes no semantic difference at all, and so it counts as redundancy.
The variety of list styles is based on real-world usage. See "The Chicago Manual of Style", 14th edition, section 8.79 (page 315): every variation of list enumeration is right there in a single nested list. Any reasonable person looking at any of those list styles will understand what they mean. Different strokes for different folks. Variety is the spice of life, and a necessity for otherwise dry documentation.
If you already have definition lists, why also have option lists and field lists?
They're semantically different. Sure you could implement option & field lists with definition lists, just as you could implement definition lists with tables. Option lists are explicitly for command-line option descriptions. Field lists are for name-value pairs where the details matter, like database records or attributes of extension constructs (directives).
If you already have literals, why have interpreted text?
They're very different things. Literals are for monospaced, *uninterpreted*, unprocessed, computer I/O text. From PEP 287: Text enclosed in single backquotes is recognized as "interpreted text", whose interpretation is application-dependent. In the context of a Python docstring, the default interpretation of interpreted text is as Python identifiers. The text will be marked up with a hyperlink connected to the documentation for the identifier given. In PEPs, there is no use for interpreted text currently (so they wouldn't be mentioned in the new-style-PEP guide, except perhaps in a footnote saying so). In the future auto-documentation tool, interpreted text will do explicitly what pydoc does auto-magically: link Python identifiers to their definitions elsewhere. But because it's explicit, interpreted text will not be accidentally misinterpreted (as can happen in pydoc).
If you already have both footnotes *and* inline URLs, why also have anonymous inline hyperlink references?
Because inline live links are useful, but nobody wants to trip over a three-line URL in the middle of a sentence.
OTOH, I have no problem with mandating standard uses, like a standard set of section title adornments.
If you're going to recommend certain ways, why not just decide what to use and be done with it? When designing a new standard, there's no point starting out with parts of it already deprecated.
PEPs are just one application of Docutils/reStructuredText. I see no conflict here. Groups often use a technology in conjunction with a conventions guide limiting the local use of that technology, for the sake of consistency or simplicity. We have such guides for Python's C code and stdlib code. (Does the Python LaTeX documentation mandate a subset of LaTeX? I know it specifies *additional* macros to use.) In the case of PEPs, I think a guide recommending certain practices would be appropriate, rather than mandating that certain constructs *not* be used. Constructs not used in PEPs are useful in other applications. Nothing would be deprecated, just "not used in PEPs". -- 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/