[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat (original) (raw)

David Goodger goodger@users.sourceforge.net
Thu, 04 Apr 2002 00:52:14 -0500

Ka-Ping Yee wrote: [Ping]

I'm not against a new markup language, but i do feel that the specification of the language is just too big. ... The current specification is about 10000 words; get it down to about 1000 and i might go for it.

I think this is the crux of the issue. Please realize that the project isn't finished yet. The verbose, comprehensive specification docs are there, because that's what was coded against, that's what was used as material for debate on the Doc-SIG and project mailing lists. Work has already begun on an introductory user document (thanks to Richard Jones; see http://structuredtext.sourceforge.net/docs/quickstart.txt).

I apologize that this wasn't available before (and I didn't expect the Spanish Inquisition!).

What's with the 32 different section title adornment characters, the optional overline, and unspecified title styles (order "as encountered")? And that's just section titles. Do we really need five kinds of lists? How about the 15 different ways to number lists? The five ways to do hyperlink targets? And that's not all...

Different strokes for different folks. Based on observation of actual usage, there's a great variety of implicit markup out there. As long as supporting the variations does not introduce ambiguity, I don't see the problem. With any markup, few users make use of all the features.

I can appreciate the desire to come up with something flexible, but this goes too far for my taste.

The markup was developed with the philosophy of "better a rich set of choices than artificial limits".

Which features should be omitted? If deemed too rich for Python docstrings (& PEPs etc.), it can be pared back. But since the full spec is out there, I doubt if anyone could come up with a generally acceptable subset.

-- David Goodger goodger@users.sourceforge.net Open-source projects: