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

[Ka-Ping Yee]

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