[Doc-SIG] On David Ascher's Rant

[David Arnold]

-->"David" == David Ascher <da@ski.org> writes:

  David> IMHO, the single most problematic aspect of Python
  David> documentation is the lack of a standard way for programmers
  David> to document their code inside the .py file, unlike e.g. POD.,
  David> and that is a shame.

agreed.

  David> There is at least one proposal to index in-code Python
  David> docstrings with TeX-like commands.  In my opinion, anything
  David> that full of backslashes and braces will never fly in the
  David> Python community.

are you refering to gendoc/settext from a few years ago?

  David> Straw Proposal 0.1 [da]:

some feedback:

- i believe that the use of "special" string variables is more
  immediately useful, and maybe more "pythonic", than XML in a
  docstring for module-level stuff like this.

  eg.

  __author__ = "David Ascher"
  __version__ = "$Revision$[11:-2]
  __date__ = "$Date$

- my personal preference would be for the RFC 822-style "tag: value"
  format over XML.  it's about equal for parsing, but significantly
  better for humans to read

- similarly, i think i'd prefer a simple, punctuation character-based
  markup over XML for method/function comments.  i really find XML
  annoying to read.


  David> That said, what I really care most about is a final decision,
  David> not the specific markup used.

agreed.  we've been dithering for years, with software being developed
to support various proposals, but never really being given the Guido
Stamp Of Approval(tm).


  David> PS: I'll pay for a new melted-wax seal if Guido lost the old
  David> one. =)

i'll chip in a coupla bucks too ;-)



d