On Thu, 1 Aug 2002, David Goodger wrote:
Ka-Ping Yee wrote:
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.
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. Other people may have different thresholds; it exceeds my threshold. 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.
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. 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. 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. 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. 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. If you already have definition lists, why also have option lists and field lists? If you already have literals, why have interpreted text? If you already have both footnotes *and* inline URLs, why also have anonymous inline hyperlink references?
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. -- ?!ng