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

[David Goodger]

Barry A. Warsaw wrote:
> I like that PEPs are 70-odd column plain text, with just a few style
> guidelines to aid in the html generation tool, and to promote
> consistency.  I think of PEPs as our RFCs and I'm dinosaurically
> attached to the RFC format, which has served standards bodies well for
> so long.  I like that the plain text sources are readable and
> consistent, with virtually no rules that are hard to remember.  More
> importantly for me, I find it easy to do editing passes on submitted
> PEPs in order to ensure consistency.

Why are PEPs converted to HTML at all then?  (Semi-seriously :-)

RFCs pre-date the Web, HTML, GUIs, and PCs.  There is a great advantage in
sticking to a text-based format, but the existing structure is very limited.
RFCs are so 20th century; don't you think it's time to move on? ;-)
Dinosaurs have a tendency to become extinct you know.

Given a small amount of use, I think you'll find the rules easy to remember.
There should be little effect on editing.  At most, Emacs may need to be
taught to recognize a bit more punctuation.

> The noisy markup in reST bothers me, although you've done a good job
> in minimizing the impact compared to other markup languages.

It's a trade-off: functionality for markup intrusion.  It's the
functionality of the processed form that's important: inline live links;
live links to & from footnotes; automatic tables of contents (with live
links!); images (don't you just *cringe* when you see ASCII graphics?);
pleasant, readable text.  The markup is minimal, quickly and easily ignored.

> I made this suggestion privately to David, but I'll repeat it here.
> I'd be willing to accept that PEPs /may/ be written in reST as an
> alternative to plaintext, but not require it.

Sure. I thought I'd emphasized that in my original post: it'd be an
alternative, the two styles can coexist.  If you want to keep PEP 0 as it
is, that's fine.  I converted it to show that its special processing was
also supported.

> I'd like for PEP authors to explicitly choose one or the other, preferrably by
> file extension (e.g. .txt for plain text .rst or .rest for reST).

I'm not keen on a new file extension (this issue has come up before).
There's so much in place on many platforms that says .txt means text files,
and reStructuredText files *are* text files, with just a bit of formal
structure sprinkled over.  Browsers know what to do with .txt files; they
wouldn't know what to do with .rest or .rtxt files.  Near-universal file
naming conventions are not the place to innovate IMHO.

> I'd also like for there to be two tools for generation derivative forms from
> the original source.
> 
> I would leave pep2html.py alone.  That's the tool that generates .html
> from .txt.

See http://docutils.sf.net/tools/pep2html.py (based on revision 1.37 of
Python's nondist/peps/pep2html.py).  Other than abstracting the file I/O and
some minor changes for consistency & legibility, the
reStructuredText-specific part is just two functions.  One checks for the
format of the PEP, and the other calls Docutils to do the work.  Even
without a new file extension, there's no need for a separate tool.

> I'd write a different tool that took a .rst file and
> generated both a .html file and a .txt file.  The generated .txt file
> would have no markup and would conform to .txt PEP style as closely as
> possible.  reST generated html would then have a link both to the
> original reST source, and to the plain text form.

Do we need a slightly less-structured text output?  I don't think so, but I
offered two alternative strategies in PEP 287:

    a) Keep the existing PEP section structure constructs (one-line
       section headers, indented body text).  Subsections can either
       be forbidden, or supported with reStructuredText-style
       underlined headers in the indented body text.
    
    b) Replace the PEP section structure constructs with the
       reStructuredText syntax.  Section headers will require
       underlines, subsections will be supported out of the box, and
       body text need not be indented (except for block quotes).

Strategy (b) has been implemented; that's what the edited PEP 287 uses.  I'd
recommend against it, but if you insist on existing PEP structure, strategy
(a) fits better although inconsistently (depending on the decision on
subsections).

> A little competition never hurt anyone. :)  So I'd open it up and let
> PEP authors decide, and we can do a side-by-side comparison of which
> format folks prefer to use.

Sure.  Once authors see what the new markup gives them, I'm sure there will
be some converts.

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