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/)