[Doc-SIG] Approaches to structuring module documentation
Fred L. Drake, Jr.
fdrake@acm.org
Fri, 12 Nov 1999 13:07:57 -0500 (EST)
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