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

[David Goodger]

[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/