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

[Guido van Rossum]

> On Thu, 1 Aug 2002, Eric S. Raymond wrote:
> > Ka-Ping Yee <python-dev@zesty.ca>:
> > > I am not against structured text processing systems in general.
> > > I think that something of this flavour would be a great solution
> > > for PEPs and docstrings, and that David has done an impressive
> > > job on RST.  It's just that RST is much too big (for me).
> >
> > And if we're going to pay the transition costs to move to a
> > heavyweight markup, it ought to be DocBook, same direction GNOME and
> > KDE and the Linux kernel and FreeBSD and PHP are going.
> 
> I would be very unhappy about having to enter and edit inline
> documentation in an XML-based markup language.

Agreed 110%.  Perhaps Eric thought we were talking about the core
Python docs?  David was only talking about PEPs right now.

> RST is not what i would call heavyweight *markup*.  It's just a
> heavy specification.  There are too many cases to know.  If you
> simplified RST in the following ways, we might have something
> i would consider reasonably-sized:
> 
>     - Choose one way to do headings.
>     - Choose one way to do numbered and non-numbered lists.
>     - Choose one way to do tables.
>     - Drop bibliographic fields.
>     - Drop RCS keyword processing.
>     - Get rid of option lists (we already have definition lists).
>     - Drop some fancy reference features (e.g. auto-numbered and
>         auto-symbol footnotes, indirect references, substitutions).
>     - Drop inline hyperlink references (we already have inline URLs).
>     - Drop inline internal targets (we already have explicit targets).
>     - Drop interpreted text (we already have inline literals).
>     - Drop citations (we already have footnotes).
>     - (Or, in summary -- instead of ten kinds of inline markup, we
>       only need four: emphasis, literals, footnotes, and URLs.)
>     - Simplify inline markup rules (way too many characters to know).
>         Instead of 100 lines describing markup rules, two lines are
>         sufficient: emphasis starts from " *" and stops at "*", literals
>         go from " `" to "`", and footnotes go from " [" to "[".

Perhaps this could be a preferred subset?

--Guido van Rossum (home page: http://www.python.org/~guido/)