[Doc-SIG] On David Ascher's Rant

[David Ascher]

On Fri, 26 Nov 1999 uche.ogbuji@fourthought.com wrote:

> David,
> 
> I confess I don't quite get it, which is too bad because I respect your 
> opinions and would like to know precisely what you're getting at.

It's all right -- I wasn't being especially clear.  That's the nature of a
rant, though, so at least you can't get me on the 'truth in advertising'
laws. =)

Here's my take on things, hopefully more rationally thought out and more
clearly expressed:

1) The current Python documentation is, in my opinion, just fine.  I think
   that moving from LaTeX to something more modern is a great idea, and I
   think that Fred is doing a beautiful job for what is a thankless task.
   I have no problem of course with the discussion on that topic.

2) IMHO, the single most problematic aspect of Python documentation is
   the lack of a standard way for programmers to document their code 
   inside the .py file, unlike e.g. POD., and that is a shame.  If nothing
   else, I think that lacking this standard is one of the reasons for the
   lack of docstrings.  If there was a good standard, then the use of
   docstrings already made in IDLE and Pythonwin (which is wonderful)
   could be made even deeper and richer, leading to a snowballing effect.

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

3) Programmers in general, smart programmers especially, try to "think
   out" all of the possible uses for something before they start to design
   it.  That's why God Invented Managers and deadlines.  We need one or
   the other.

> The way I see it, your key argument with Manuel's proposals would be that he 
> plans to inflict TeX on Python authors.  I agree that that is a bad thing, and 
> I also wouldn't want to inflict XML on Python Authors.  I don't think that's 
> an alien sentiment here, but your rant makes it sound that way.

> So, what am I missing?

Possibly nothing.  I posted in a moment of emotion, which is never a good
idea.  I apologize for the rant.  I suspect that what I was really
reacting to was a combination of:

  - puzzlement as to the motivations for Manuel's proposal,
  - a personal frustration with seeing design-by-committee lead to inaction
  - a strong visceral reaction against TeX-style markup in Python.

I don't mind XML markup so-much, btw, and I suppose no one else in the
HTML age minds much as long as they don't have to mess w/ anything beyond
<foo>...</foo>.  As soon as you allow anything beyond the trivial, you
lose 50% of the audience.  KISS (Keep It Simple, Stupid) rules for these
sorts of things.

Here's what I'd most like to see in the area of in-code doc (I have no
constructive opinion on the 'large' documents markup issue): a definition
for a set of entities (if that is the right word) to use in docstrings for
modules, classes, functions and methods.  After two weeks of discussion
*at most*, Fred brings it to Guido, Guido gets his old melted-wax seal and
stamps his approval on it, and then we advertise the heck out of it.  The
code will follow.

Straw Proposal 0.1 [da]:

  """
  <AUTHOR>David Ascher</AUTHOR>
  <VERSION>1.0</VERSION>
  <DATE>20/10/96</DATE>
  <DESCRIPTION>This is a module with one function in it.</DESCRIPTION>
  <URI>...</URI>
  """

  def len(input):
    """\
    <DESCRIPTION> Returns the length of the input sequence </DESCRIPTION>
    <ARGUMENT name="input" type=sequence> 
        The input sequence
    </ARGUMENT>
    <RETURNTYPE> IntType </RETURNTYPE>
    <INDEXWITH>len, lenth, ln</INDEXWIDTH>
    """
    ...
  
FWIW, I'm really not sure that the above is significantly easier to parse
in the long run than a more Pythonic:

  """
  Author: David Ascher
  Date: 10/25/99
  ...
  """

  def len(input):
      """\
      Description:
          Returns the length of the input sequence.
  
      Arguments:
         input (sequence) -- The input sequence
    
      Return Type: IntType

      See Also: len, length, ln
      """

provided we make explicit exactly the format (just like Python syntax is
formalized and parseable) and keep the fancy stuff (embedded URLs,
hyperlinks, etc.) to a single escape code (e.g. like what Mark Hammond was
pushing for months ago -- see June 1998 archives). That said, what I
really care most about is a final decision, not the specific markup used.  
That's why I think that what we need is a Guido Stamp Of Approval.

--david 'ranted out' ascher

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