[Doc-SIG] Approaches to structuring module documentation

[Paul Prescod]

Manuel Gutierrez Algaba wrote:
> 
> Most of my doubts can be resumed into one: The need of "high level
> information".

The lack of documentation for high level features (or the poor indexes
for them) cannot be solved by new documentation systems. It must be
solved by new *documentation* (or at least indexes). There is nothing in
the current system that precludes solving the system you describe.

> I've never needed to know the signature of a function,
> or If i needed it , i found it seamlessly. I don't need javadoc,
> nor pythondoc, not at all certainly, I can read the .py , which
> are more compact than html info of java, usually.

But not hypertext navigable, not nicely formatted and not appropriate
for printing out.

> 
> "\indexexamplelambda" or 
> "\indexsocket"

> Indexing for the masses !! Masses of indexes !! Simple and effective!

I agree with a need for indexing, but I think it is a separate issue
with separate solutions. Those solutions are mostly unrelated to the
markup strategy problem. As you point out, the markup for indexing is
simple. Has Fred points out, the name management is tricky!

-- 
 Paul Prescod  - ISOGEN Consulting Engineer speaking for himself
"Like most religious texts, the XML 1.0 spec has proven itself 
internally-inconsistent, so we're going to have to invent some kind of 
exegetical method now to show how it's really all an allegory." - Anon