[Python-Dev] Re: Docutils/reStructuredText is ready to process PEPs
Guido van Rossum
guido@python.org
Thu, 01 Aug 2002 11:22:06 -0400
> 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/)