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

[Barry A. Warsaw]

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

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

To brand them with a Python banner and give them some hyperlinks. <wink>

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

They also become the oil that drives our engines of industry, to twist
an analogy.  :)

An of course RFCs are also converted to html:
http://www.faqs.org/rfcs/rfc2822.html

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

We'll see!

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

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

Taken to the extreme, why do we even use a text based format at all?
We could, of course, get all that by authoring the PEPs directly in
HTML.

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

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

Cool.

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

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

Don't most servers default to text/plain for types they don't know?
I'm pretty sure Apache does.

If a file extension isn't acceptable, then I'd still want the
determination of plaintext vs. reST to be explicit.  The other
alternative is to add a PEP header to specify.  I'd propose calling it
Content-Type: and use text/x-rest as the value.

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

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

Fair enough.  Let's do this: send me a diff against v1.39 of
pep2html.py.  I just downloaded docutils-0.2, but I'm not sure of the
best way to integrate this in the nondist/peps directory.

- If we do the normal setup.py install, that's fine for my machine but
  it means that everyone who will be pushing out peps will have to do
  the same.

- If we hack pep2html.py to put ./docutils-0.2 on sys.path, then we
  can just check this stuff into the peps directory and it should Just
  Work.  We'd have to update it when new docutils releases are made.

Suggestions?  Mostly I'd like to hear from others who push out new PEP
versions.  Would you rather have to install a disutils package in the
normal way locally, or would you rather have everything you need in
the nondist/peps directory?

OTOH, if plaintext PEPs work without having access to the docutils
package, that would be fine too (another reason perhaps for an
explicit flag).

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

    DG> Do we need a slightly less-structured text output?

Maybe not.  I'd prefer to have it, but if I'm alone there then I'll
give up that crusade (or at least call YAGNI for now).
    
    DG> I don't think so, but I offered two alternative strategies in
    DG> PEP 287:

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

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

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

a) might also mean you'd have to reflow paragraphs to fit in the
column width restrictions.  I'd prefer a) but it may be more
problematic.  Moot if YAGNI prevails.

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

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

Let's find out.
-Barry