[Doc-SIG] On David Ascher's Rant

[Fred L. Drake, Jr.]

M.-A. Lemburg writes:
 > I guess doc strings are just as personal to the programmer
 > as indention or naming styles: you won't get everybody to agree
 > on one way to do it.

  We don't have to get everyone to agree, or even to write the
standard format docstrings.  We need to determine one reasonable
format and get Guido to agree sanction it.  The rest will fall into
place over time.

 > Besides, I don't think this is really needed: as long as the
 > programmer can provide routines to parse his code everything
 > should be fine. This could e.g. be implemented by subclassing
 > a reader implementation which then passes the parsed tokens
 > to other code processing them for some other use.

  Nice idea.  I won't waste *any* time supporting it.
  We only *need* a very small number of things for the "next
generation" documentation to succeed (in terms of formats):

    1. One format for in-source module-reference documentation.
    2. One format for non-source module-reference documentation.
    3. One format for non-module-reference documents.

  Add to this a reasonable set of very easy to use tools that do a
good job of formatting documentation for hypertextual perusal, and
we've got a minimal system.  Specific output formats (HTML, GNU info,
HTML Help) are easily created once the first one is done.  Typeset
versions for printing are relatively easy, and nobody prints anything
anyway.  ;)
  Clearly I've abstracted away a lot of details, and there's more
design work than whacking at scripts for a couple of hours will avoid, 
but I really think that's the essence of what we need to do here.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives