Re: using docbook for API reference documentation

[Steinar Bang <sb@dod.no>]

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

> Rather, I was wondering about the document's structure itself, i.e.
> mappings from modules to sections (even if there are many nesting
> levels such as is typical for java and python ?), and so on.

For Java it would make sense to have sections for all packages that
have content, and for all packages that are common for the packages
that have content.

I.e. if you have the following packages containing classes or
interfaces: 
 com.somecompany.a.b.c
 com.somecompany.a.d.f
it would make sense to create the following sections:
 <section>
  <title>Package com.somecompany.a</title>
  <section>
   <title>Package com.somecompany.a.b.c</title>
   ...
  </section>
  <section>
   <title>Package com.somecompany.a.d.f</title>
   ...
  </section>
 </section>

I'm unsure how well that approach would work in eg. Python or C++ (I
don't know Python, and haven't used namespaces all that much in C++).