[Doc-SIG] New PEP: reStructuredText Standard Docstring Format

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> The updated PEP can be found at
> http://docutils.sourceforge.net/spec/pep-xxxx.txt,
> until it's assigned a number.

I strain to find more niggles - but yes, by hard enough work anything is
possible...


"""There is no significant downside to using reStructuredText."""

Hmm. Somehow that feels like damning with faint praise. I think this
needs a more positive way of saying the same thing. Or to be left out,
if a better phrase can't be found. (The pedant in me [1]_ immediately
wants to know whether your idea of a "significant" downside matches
mine, for a start.)

Perhaps something like (forgive the "sentence starting with
'because'")::

   Because reStructuredText reads as sensible plaintext, there
   is no significant downside for the reader of such documentation,
   whilst the advantages are still available.

(well, I felt some alternative proposal was better than none, and this
does defuse that "significant" a bit)

.. [1] some would argue "the pedant coincident with me"
   would be better phrasing.

"""The Docutils project is at the point where standalone
reStructuredText documents can be converted to HTML."""

...and other output formats are in preperation? (I know you address that
in the next paragraph, but that's more in the docstring context)

Also, aren't there some tool users keeping track of events - both
HappyDoc and one of the Wikis? Might it be worth finding out explicitly
if they are considering adopting reStructuredText as one of their bag of
input formats?


Anyway, looking good...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)