[Doc-SIG] Approaches to structuring module documentation

[Moshe Zadka]

On Fri, 12 Nov 1999, Fred L. Drake, Jr. wrote:

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

The former. The later would be classified in the "documentation is like 
sex: when it is good it is very good, and when it is bad, it is better
then nothing" dept. I.e., it is better to have as much semantic
information, but even without it, the docs are useful.

>   My thought is that the profiler and debugger both need to be
> documented in two ways: as modules
<snip>
>and as user-support facilities
<snip>

I agree. In fact, the documentation for pdb is horrible as module
documentation. It is quite good as a user's manual.

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

Hmmmmm....define User's Manual. What do you want from it?

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

Again, it is a "real" problem, not an artifact of the solution: either you
have AI, or you patiently tell the computer what every word means, or you
live in a non-perfect world. Most solutions are a combination of all three
approaches: use a bit of smart in the processor, put some markup, and live
with the fact that some information will require a human to discover ;-)

<snipped discussion of vocabulary>
>   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.

It doesn't matter: you'd still have to use the micro-document approach
for this to work. I just painted a rosy picture of what it would buy you.

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

Oh, I forgot to spec that XPyML is a proper subset of PyML, so you can
author directly in that. PyML is just thin syntactic sugar, so you can use
some SGML minimizations, which are useful in practice. We can choose just
a few (e.g., I'm for <minimized/word/, mainly because "/" is a rare word
in Python code, and invalid in identifiers)

But I can live with straight XML, if that's the party line.
--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.