[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-apps] Re: using docbook for API reference documentation
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]