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

[Barry A. Warsaw]

>>>>> "DG" == David Goodger <goodger@users.sourceforge.net> writes:

    DG> I hereby formally request permission to deploy Docutils for
    DG> PEPs on Python.org.  Here's a deployment plan for your
    DG> consideration:

I'm sympathetic to your aims, but I have reservations.  As lightweight
as reST is, it's still too heavy for me.  Ka-Ping described some of my
feelings quite well so I won't repeat what he said.

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.

The noisy markup in reST bothers me, although you've done a good job
in minimizing the impact compared to other markup languages.  Magical
double colons, trailing underscores, etc. are jarring to me.  I wonder
how tools like ispell will handle some of it (I haven't tried it on
your reST source versions).

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

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.

-Barry