Re: [docbook-apps] Re: using docbook for API reference documentation

[Stefan Seefeld <seefeld@sympatico.ca>]

Steinar Bang wrote:

> 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.

In other words, you suggest to collapse packages that have a package
as single entry ?

> 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++).

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.

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' ?

Thanks,
		Stefan