[Doc-SIG] Re: Docstrings [was: On David Ascher's Rant]

[David Ascher]

(Sorry, but I felt the need to change the Subject line.  My wife looked at
my inbox and said "you're ranting?")

On Mon, 29 Nov 1999, David Arnold wrote:
>   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?

No, I was referring to Manuel's proposal, which I obviously misunderstood.
I don't recall the gendoc/settext proposal.

> - 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

I think it's important to note that these will still be in strings, and
that one should not confuse them with code.  

Some reactions to this weekend's posts:

1) Manuel's proposal is interesting, but IMHO much broader in scope than
   what I feel is needed and doable.  Indexing ideas is a
   larger-than-encyclopedic endeavor, and I could but won't argue its
   impracticality on statistical grounds alone.  Suffice it to say that I
   agree with Manuel that people are lazy and that it won't work. 

   More positively, Manuel, do you agree that the kind of markup that I
   advocate (a la POD/javadoc) is a subset of yours (in other words that
   "Author" and "Argument 1" are 'trivial ideas', hence belong to the set
   of ideas? And that if this 'minimal' markup is used, then you can use
   the tags too along with the other, higher-level notions that you
   propose?

2) So far, folks seem to like a 'lightweight' structure for docstrings.
   (note that by lightweight I do not mean ambiguous or vague [*]).
   MAL wants to allow multiple formats as long as the person writing the
   docstring writes a parser for his/her specific format.  That's fine
   with me as long as there is a format which we can assume is readable by
   default without *having* to write such a parser.  Uche has mentioned
   that he 1) agrees that XML shouldn't be imposed on Python Authors, and
   that 2) XML is easier to parse than StructuredText.  While I grant him
   both, I'd like his reaction to this specific point.  

   I would like to claim that we can define a format which is
    - easily learned
    - easily parsed and debugged
    - rich enough
    - extensible enough
    - pleasing to the eye

   I will make a concrete proposal in a seperate message titled "docstring
   grammar".

3) The i18n issue is IMHO a red herring.  We can allow a 'keyword
   renaming' facility so that I can start a module with:

	import docstring
	docstring.set_language('Francais', 'Quebec')

   and then I can use Quebecois keywords in the doc, as long as there was
   a table mapping the default (US-English) keywords to the Quebecois
   keywords. Would that be OK with you, Marc-Andre?  After all, 'import'
   is an English word, and no one complains about that.  I once programmed
   in a version of Basic where the keywords were translated in French, and
   I can testify that it was a massive failure.

--david 

[*]: I have found StructuredText as implemented in StructuredText.py to be
     somewhat vague and non-trivial to use to produce exactly formatted
     doc.  This is probably due to its bigger aims than what I have in
     mind for this.