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

[Ka-Ping Yee]

On Thu, 1 Aug 2002, David Goodger wrote:
> 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.

If you took reST and removed the features i listed, you would have a
markup system with paragraphs, multi-level headings, nestable bullet
lists and numbered lists, definition lists, literal blocks, block quotes,
tables, inline emphasis, inline literals, footnotes, inline hyperlinks,
and internal and external hyperlink targets.

Sounds pretty powerful to me.  I find it strange that you would call
this "next to useless".

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

I don't want to have to debug my text.

If the markup is simple enough, determining the output requires very
little context (a line or two); this means i can be sure what i'm going
to get.  Auto-numbering expands the context so any part of the entire
document can affect the transformation of another part of the document.

> A small price, IMHO.

The difference between writing a document once and *knowing* that it's
correct, and having to compile-test-debug a few times, is a big cost.

> I've volunteered to do the processing, so there should be no impact on
> anyone.

Huh?  I don't know what you mean here.  The design of reST impacts
everyone who has to read to write documents in it.

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

Both.  Why have an assortment of 32 random punctuation characters,
for a total of 64 different ways to do a heading?  Who's going to
remember what the characters are, anyway?  Pick one or two and stick
to them.  There are really only two obvious ones: '-' and '='.

You can differentiate heading levels by indenting the heading, one
space per level.  It would be vastly easier to tell what level a
heading was at by looking at its position, rather than running all
the way back to the beginning of the document and counting the number
of different heading styles that appear.

> 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".

That's a backwards argument.  It's good that reST titles look
like titles.  But that doesn't mean reST has to recognize all
possible things that might look like titles, as titles.

It's a lot easier to say "just underline your title with a row
of hyphens" than "choose one of the following list of 32 random
punctuation marks to underline your title; and optionally overline it;
oh, but actually we think you should use only the following subset
of the 32 punctuation marks..."

> > 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).

All three are about associating a list of things with their
corresponding definitions.  Distinguishing whether the things
being defined are options or not is just as unnecessary as
distinguishing shopping lists, to-do lists, hit lists, etc.


-- ?!ng