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

[Ka-Ping Yee]

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.

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 "[".


-- ?!ng

"This code is better than any code that doesn't work has any right to be."
    -- Roger Gregory, on Xanadu