[Doc-SIG] Approaches to structuring module documentation

[Moshe Zadka]

On Thu, 11 Nov 1999, Fred L. Drake, Jr. wrote:

>   Well, now that things have quieted down a little (where?!), I'll
> stir things up a little.

Very good.
<snipped some generic discussion>

>   MICRODOCUMENT APPROACH:  Multiple DTDs are used to encode
> document-level information and module reference material.  Let's only
> consider the case of one DTD to handle module reference material, and
> a small number (1 or 2) of document-oriented DTDs; possibly one for
> "sections" and one that could be used to compose sections and module
> references into chapters and manuals.

Well, no one who has read other mails of mine here will be surprised at
my whole-hearted embracing of this approach.

<snipped some things, among them discussion of how the whole library
reference is formulaic, except the debugger and profiler>
> I'm not
> sure if allowing this level of flexibility is good or bad; I could
> make the case for both. 

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.

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

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
program, I will paint a rosy picture of how beautiful the future could be
if we used microdocuments, and written a "pydoc" preprocessor:

pydoc htmllib --> show the documentation of htmllib
pydoc string.reverse --> show the documentation of string.reverse
pydoc -q reverse --> show all FAQs which have the word reverse in them
pydoc -f reverse --> search for a function called "reverse"
.
.
.
(For those of you on WIMP interfaces, substitute a dialog, and a fancy 
window which formats the documents)

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.
--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.