[Python-Dev] Re: Docutils/reStructuredText is ready to process
Thu, 1 Aug 2002 04:22:19 -0700 (PDT)
On Thu, 1 Aug 2002, Eric S. Raymond wrote:
> Ka-Ping Yee <firstname.lastname@example.org>:
> > 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 "[".
"This code is better than any code that doesn't work has any right to be."
-- Roger Gregory, on Xanadu