[Doc-SIG] Approaches to structuring module documentation

[Manuel Gutierrez Algaba]

On Mon, 22 Nov 1999, Paul Prescod wrote:

> Sorry for the delay on this message. I need a long plane flight to be
> able to think about this issue properly.
> 
>  * content
>  * structure of the content
>  * presentation
> 
> Okay, they are all related but they are still different. If somebody
> can't find something, I would tend to try to fix that in the
> presentation first, and then in the content and finally in the structure
> if all else fails. Let's not jump right to the structure. Consider this
> analogy: someone using a word processor cannot figure out how to bold
> something so we decide to change the file format? Sure, there is a small

I agree. The first issue is supply content to the user, and the 
structure of the content will be resolved when we have enough
content to build it. 

The TeEncontreX (www.ctv.es/USERS/irmina/TeEncontreX.html)
provides the less structure possible, it's pure marking of contents
and a bit of relationship between contents, and it's pure presentation..

I really can't understand why people don't get interested in it. 
I think most people think that the complex solution for a problem
is the best solution....

> Also, consider our choices a graph with two axes:
> 
>  * specificity of markup
>  * granularity ("library", "package", "module", "class) of file

 specifity of markup 
 |     I                     J
 |             X
 |
 |
 |     T
 |------------------------------------
    library package module class          granularity

T : TeEncontreX
J: javadoc
X: XML
I: emacs texinfo
?? It'd be this way ? If so, it's clear that specific markup
makes it more difficult, and that granularity is not a problem.

> documentation feature built into the grammar. I would advise that it
> should NOT be XML. In fact it should probably be roughly JavaDOC or
> POD-ish so that we aren't reinventing the wheel.

I think we must invent the wheel, or at least improve it. I don't 
like javadoc, it seems to me very low level ( type-driven ), useful
for java, but python deserves a higher level stuff.  The doc of
a language is related to the very nature of that language, it's not
the same a prolog documentation than COBOL doc. As I think Python
is Lisp with OO, it should have a Lisp-ish doc... The question
is : how is Lisp doc ? :-) 

BTW: Are you the Paul Prescod who wrote "Manual de XML" with 
Charles F. GoldFarb . Prentice  Hall and... ?

Regards/Saludos
Manolo
www.ctv.es/USERS/irmina/TeEncontreX.html   /texpython.htm

  Nasrudin walked into a teahouse and declaimed, "The moon is more useful than the sun." "Why?", he was asked. "Because at night we need the light more."