[Doc-SIG] Approaches to structuring module documentation

[Manuel Gutierrez Algaba]

On Fri, 12 Nov 1999, Fred L. Drake, Jr. wrote:
<Basically, you say that TeEncontreX is indexing and that
is orthogonal of Micro-document, ....>
> 
>   Library science types would call this kind of data marking
> "indexing". 

I do admit that At the beginning they were simple indices, now
they still seem indexes. But you say that "good indexing" is 
crucial. 

If you say it's orthogonal, that means it's independent, so
indexing could start today. But indexing means creating a 
vocabulary, a lexicon. This can be created on the fly at the 
same time the indexing goes on. But when you have such a lexicon,
you would be tempted of using such lexicon or relationships
amongs indixes in your XML marks. So, there's an implication
indexes --> XML

Second, if you have created HTML pages or LaTeX from TeEncontreX
index system, then you'll have a kind of Python Documentation.
If both micro-doc and document-centric have a strong implication
in the generation of Python Doc, it's clear that TeEncontreX
is not so orthogonal. You can say that it's a very weird thing,
or not usual, but in the three fields:
- info storage
- info representation
- lexicon definition

TeEncontreX and XML have a good intersection of functionalities.

And, it's not simple indexing, LaTeX indexing, for example,
doesn't alter the structure of info. TeEncontreX ( it means 
Te Encontre --> I found you ) isolates the info to be indexed
from the rest, so, if you take a Document-centric stuff and you
apply TeEncontreX method in it, you don't have the same doc any 
longer,
but the old doc, divided and attributed in 100 or 200 parts. It's
like an XML, but whose structure is not based upon marks , it's
based in the meanings of indexes and how are related to each other.


Another comment: indexes usually are one-dimensional. 
If you have an item described by many indexes you have something
multi-dimensional or an object.

And finally, whatever decision is chosen. Let it be simple and 
natural, remember that not everybody can speak XML.

Indexes may be help you in discovering the Lexicon of python,
the Knowledge Zones of Python and with this you can
decide the size and depth of any micro-doc or document-centric.

So, I see that Indexes have an inmediate pay-back ( for the user)
and they help further XML (and not XML ) design. Why not start with
them ?

Regards/Saludos
Manolo
-------------
My addresses / mis direcciones: 
a="www.ctv.es/USERS/irmina"
b=[("Lritaunas Peki Project", ""),
   ("Spanish users of LaTeX(en Espanyol)", "/pyttex.htm" ),
   ("page of drawing utility for tex ", "/texpython.htm" ),
   ("CrossWordsLand","/cruo/cruo.html")
   ]
for i in b:
  print i[0],":", a+i[1]

  Well, you know, no matter where you go, there you are. -- Buckaroo Banzai