[Doc-SIG] Approaches to structuring module documentation

[Fred L. Drake, Jr.]

Moshe Zadka writes:
[re: formulaic v. more flexible module references]
 > Here's a simple argument against it: in the TODO list, there are requests
 > for explanations of how to use <suprise!> both the profiler and the
 > debugger. Guido marked it "a library chapter isn't enough?". And he's
 > right, but having the structure so flexible tempted guido to put the
 > chapters in the library reference, instead as seperate documents.

  I'm not entirely sure what you're against: allowing general document 
structure in the library reference manual, or allowing less structured 
content to serve as module references.  But I understand the problem
you're referring to.
  My thought is that the profiler and debugger both need to be
documented in two ways: as modules (they are, and their interfaces are 
directly useful), and as user-support facilities (with more narrative
documentation).  The current problem is that these components are
conflated.  The narrative "how-to-use-it" documentation should be
removed from the Library Reference and made part of a the User's
Manual, which simply hasn't been written (yet -- any takers?).

 > >   That's a 200% increase in line count and a 150% increase in file
 > > size.  The later isn't much of an issue, but the former is because it
 > > seriously impacts readability.
 > 
 > Ummmm...it really depends on how much semantic information you put in.

  Yes, but there's a good bit I expect to be present regardless.
  I think there's a lot to be gained by being able to say "this method 
expects a pathname, an optional string, and an optional integer, and
returns a file-like object."  Saying it in natural language is easy
(if tedious, given the number of functions/methods about which we can
give that level of information), but saying it so tools can handle
it... requires a lot of markup.  ;-)
  We'll need to define a "vocabulary" that can encompass built-in
types, "protocols" (or interfaces, or whatever they can be called),
and actuall classes.  Class names are easy, but protocols and built-in 
types need to be added.  Variations include being able to say "exactly 
this" or "this or a subclass," etc.  It probably makes sense to be
able to say "non-complex numbers," or "standard number types," or
"non-negative integers," etc.

 > Here's the strongest argument for the microdocument approach: as someone
 > who uses both Perl and Python (though I much prefer the later), I see the
 > enormous benefit of a program like perldoc, which could only be written
 > on a microdocument based infrastructure. For those not familiar with this

  Actually, my inclination would to run "pydoc" off a back-end
database rather than directly off the XML.  The database could be
built once from the document sources and then contain data that's been 
as pre-digested as makes sense.  That would be a lot faster than using 
XML; the entries could be pickled objects or whatever makes sense.

 > We might need a PyML such that XML<PyML<SGML (that is, PyML is not an
 > application of XML, only of SGML) and a convertor PyML->XPyML such that
 > XPyML is an application of XML. That way we could have whatever terseness
 > from SGML we care to implement, and all the power of XML at our back.

  I think we can avoid this.  I'd opt simply to use XML and be done
with it before using SGML only as a way to author XML.  If anyone
really wants to do this, the tools are easy enough to build given
ESIS-generating SGML & XML parsers & the tools in
Doc/tools/sgmlconv/.


  -Fred

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