[Doc-SIG] SGML Python docs

[Fred L. Drake]

John Skaller writes:
 >         Actually, I think it is. There are a lot of formats around,
 > and all have advantages and disadvantages. The biggest advantage
 > for any one author is probably familiarity. The biggest advantage

  My understanding of your statement that precipitated this was that
you thought "we" (prob. meaning Guido & I) were using the formats
we're using (LaTeX) simply because that's what we like.
  I don't know what went into the original decision to use LaTeX, but
I expect it included the issue of availability.  I've continued to use 
it in part because there's a lot of documentation on TeX/LaTeX (both
free on the web and published in books), because I know it (*not*
because I like it -- I'm quite ambivilant), because it's free, and
because I can make it do pretty much everything we need it to do.
When that last item is no longer true, I will not hesitate to switch
formats to something that will do what we want it to do.

 >         Interscript has decisive 'technical' advantages over all the other
 > formats.
 > For a start, it can generate the lot, automatically, so it subsumes them all.

  I'm not at all convinced that this is a benefit, but that can be
reasonably debated either way.  Documenting that something is not yet
documented (which seems the only real option when there isn't
documentation) does not seem valuable, and can be distracting.

 > by program authors, alieviating the current problem of lots of undocumented
 > modules, or, worse, incorrectly documented modules.

  The problem of undocumented modules can only be fixed by someone
writing documentation.  Whether the documentation is embedded in the
module or encoded in a separate file (as LaTeX, SGML, XML, or
whatever) is a minor technical issue.
  The problem of incorrect documentation doesn't go away.  Perhaps it
becomes easier to keep the documentation up to date, but it will never 
be "free", so documentation will not follow implementation in
lock-step.  This is not a technical issue so much as a human issue; we 
are limited and so is our time.  (Is this a bug or a feature of time?
Careful; trick question!)


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191