ANN: New PEP Format: reStructuredText

[Bengt Richter]

On Fri, 30 Aug 2002 00:23:15 -0400, David Goodger <goodger at users.sourceforge.net> 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

    http://docutils.sourceforge.net/docs/rst/quickref.html

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:
>
>    http://docutils.sourceforge.net/
>

Whenever I encounter yet another markup language (BTW, are you guys monitoring
http://yaml.org/spec/ ;-), 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::end_of_literal::
<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.
end_of_literal

For rendering in HTML, I might expect to get

        <p>This:
        <pre>
&lt;This is arbitrarily indented and might be verbatim copied &amp; pasted from anywhere&gt;.
 end_of_literal ?? -- no! It has to be by itself on a final line.
</pre> 

(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::
<arbitrary-except-not-including-xxx-on-line-by-itself>
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)

    D:\Python-2.1\Grammar\Grammar

file !/?

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

Regards,
Bengt Richter