ANN: New PEP Format: reStructuredText

Bengt Richter bokr at
Wed Sep 4 15:08:23 EDT 2002

On Fri, 30 Aug 2002 00:23:15 -0400, David Goodger <goodger at> wrote:

>With many thanks to Barry Warsaw for his help and patience, I am
>pleased to announce that a new format for PEPs (Python Enhancement
>Proposals) has been deployed.  The new format is reStructuredText, a
>lightweight what-you-see-is-what-you-get plaintext markup syntax and
 ^^^^^^^^^^^ -- well, the rudiments are light weight ;-)

>parser component of the Docutils project.  From the new PEP 12:
>    ReStructuredText is offered as an alternative to plaintext PEPs,
>    to allow PEP authors more functionality and expressivity, while
>    maintaining easy readability in the source text.  The processed
>    HTML form makes the functionality accessible to readers: live
>    hyperlinks, styled text, tables, images, and automatic tables of
>    contents, among other advantages.
I like it, but I can see symptoms of "we-can-do-anything-with-this" enthusiasm ;-)

I think the "cheat sheet" at

is a better intro than the other intro's, because it's concise and visual
(though some table stuff appears broken in my NS4.5 browser).

>Docutils and reStructuredText are under active development.  Input is
>very welcome, especially HTML rendering/stylesheet issues with
>different browsers.  We welcome new contributors.  If you'd like to
>get involved, please visit:

Whenever I encounter yet another markup language (BTW, are you guys monitoring ;-), I look for fodder for my pet bête, and if I find an
un-nestable and/or otherwise restricted literal-content quoting construct, my
pet grunts happily (which it is doing ;-)

So I'd like to suggest an optional variant of the literal block, to mimic "here document"
functionality. E.g.,

<This is arbitrarily indented and might be verbatim copied & pasted from anywhere>.
 end_of_literal ?? -- no! It has to be by itself on a final line.

For rendering in HTML, I might expect to get

<This is arbitrarily indented and might be verbatim copied & pasted from anywhere>.
 end_of_literal ?? -- no! It has to be by itself on a final line.

(I.e., '&', '<' and '>' converted to entity refs and otherwise no change between the <pre></pre>).

("end_of_literal" is of course an arbitrary string chosen or generated so as not to occur within
the quoted text).

Re YAML, perhaps a .. yaml:: yamlDoc_ directive to include a rendering of YAML content might
do something useful? (I won't mention .. xml:: xmlDoc_ ;-)

BTW, you could also use doc-here quoting to delimit the scope of a directive, e.g.,

    .. doit::xxx::

A last comment/question: It-would-be-nice-if-there-were/is-there-a grammar file for
reStructuredText like, e.g., Python's (comes with source distro)


file !/?

Sorry if this repeats stuff covered in project docs/threads/faqs/todos. Have only browsed
spec and PEP and cheat sheet so far...

Bengt Richter

More information about the Python-list mailing list