ANN: New PEP Format: reStructuredText
Bengt Richter
bokr at oz.net
Wed Sep 4 15:08:23 EDT 2002
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>
<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.
</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
More information about the Python-list
mailing list