Re: using docbook for API reference documentation

[Steinar Bang <sb@dod.no>]

>>>>> Stefan Seefeld <seefeld@sympatico.ca>:

> I think mapping modules to sections would work in all these
> languages.  But I'm questioning the usefulness of such a structure
> in a document such as a book, at least when the nesting level gets
> high.

That's why I thought of "pruning" away those modules that don't
contain anything interesting in themselves.  Ie. to keep both the
number of sections and the nesting level down to those modules that
are interesting.

> As an alternative, consider a single section containing some
> representation of the whole tree, followed by a flat list of
> sections for 'leaf modules' (i.e. those containing things other than
> modules).

> Wouldn't that be more 'ergonomic' ?

Using sections give a good navigatitional structure for chunked HTML.
I'm a Opera user, and thanx to the meta tags that DocBook XSL I can
navigate through the chunked HTML structure on keypushes alone.

Very ergonomic!

Not sure how good it would be in eg. print.