[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[David Goodger]

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:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net