[Python-Dev] Re: PEP 287: reStructuredText Standard Docstring Format (original) (raw)

Samuele Pedroni pedroni@inf.ethz.ch
Fri, 5 Apr 2002 13:33:22 +0200

Kent Pitman (KMP) often talks about programming languages as Political Parties (a brilliant intuition).

I honestly wonder whether to the Python party really corresponds more-or-less just one documentation format party, a silent majority perhaps.

And whether Docutils (formerly DPS) will be up to this ambitious design claim in PEP 258 (revision 1.2):

Intermediate Data Structure

... The DTD defines a rich set of elements, suitable for any input syntax or output format

or is it already optionless (anyway it is not finished).

sometimes-I-wish-I-had-a-real-&-working-Erik-Naggum's-mode- (a-KMP's-mode-would-be-better-and-more-pythonic-but-even-more- ambitious)-ly y'rs.

PS: the funny thing is that I do not dislike structured text formats in general, but auto-documenting is reducible to that ?

----- Original Message ----- From: David Goodger <goodger@users.sourceforge.net> Newsgroups: comp.lang.python Cc: Richard Jones <rjones@ekit-inc.com>; <python-dev@python.org>; <doc-sig@python.org> Sent: Friday, April 05, 2002 6:33 AM Subject: [Python-Dev] Re: PEP 287: reStructuredText Standard Docstring Format

Thank you to everyone who has commented on PEP 287, be they in favor, well-meaning but opposed, or ill-wishing troll ;-) [1]. I have been otherwise busy and haven't been able to keep up with replies, but I have read and kept a record of all the posts so far (and will, for posts yet to come) for consideration and reference when revising the PEP. I may not be able to offer timely replies to all the posts; ultimately the revised PEP will serve as an umbrella reply.

.. [1] Actually, the posts opposed and even the trolls are often the most useful, since they point out weaknesses and help strengthen the arguments. The number of people posting in favor of the PEP was roughly the same as the number opposed, but supporters tend to be silent while protesters tend to be quite vociferous and relentless. Over the weeks to come, I will be revising PEP 287 and related PEPs 256-258, merging the reStructuredText and DPS projects into the renamed Docutils project, and producing a "road map" describing the big picture. Further suggestions for improvement are welcome. .. reStructuredText: http://structuredtext.sourceforge.net/ .. DPS: http://docstring.sourceforge.net/ .. Docutils: http://docutils.sourceforge.net/ A special thanks must go to Richard Jones for taking up arms (or keyboard) in my stead, and for taking the initiative to start work on A_ _ReStructuredText Primer. In hindsight it was much needed, and it's coming along nicely. Thanks Richard! .. A ReStructuredText Primer: http://mechanicalcat.net/tech/quickstart.html -- 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

Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev