Re: [docbook-apps] auto-index, HOWTO

[Stefan Seefeld <seefeld@sympatico.ca>]

Bob,

thanks a lot for your suggestions.

However, as my goal is much more to find the most appropriate docbook to 
*generate* from parsed source code (as this is what the tool I'm writing 
does), I'd like to focus on that. In general I don't have control over 
what XSL users will apply to format that docbook.

Nonetheless, I'm going to experiment with your suggested changes, if 
only to learn what can be done.

Bob Stayton wrote:

> Maybe I don't understand your usage of the term "qualification" here, 
> but I don't see how your notation adds any information for the reader:
> 
>> foo(), B::foo(), C::foo()
>> foo(int), B::foo(int)

Qualification means to disambiguate 'foo' by prepending the scope, 
yielding 'B::foo' and 'C::foo', etc.

> It seems to be repeating the indexterm as a suffix to the section title, 
> which to me makes the entry harder to read.  How would this look for 
> indexterms in section titles with more than one word?

You are right, there is redundancy, which is introduced because the 
index term pointing to the section, not the indexterm-generated anchor, 
forces me to inject new sections to get the references and labels right.

So, if I had full control over both, the document content *and* the 
formatting, I would be able to generate those prefixes by looking at the 
enclosing section titles.

Not being able to provide your suggested trick to all the users of my 
tool, I have to use fully qualified ids in the generated document (in 
the 'secondary' element, as Dave suggests).

So here are example API Reference manuals I generate from source code, 
using my DocBook formatter:

Using the XHTML stylesheets:
http://synopsis.fresco.org/docs/examples/Paths/docbook/index.html
and using the FO stylesheets:
http://synopsis.fresco.org/docs/examples/Paths/docbook/Paths.pdf

(Note that I'm using 'typed' indices, i.e. one 'Types' index, and one 
'Functions' index. This matches users' expectations from writing similar 
documentation using TexInfo.)

I would very much appreciate any feedback people might have concerning 
my use of DocBook to represent APIs. Surprisingly, I couldn't find any 
other (free) API documentation tools that use DocBook (I did play a bit 
with the dbdoclet plugin for javadoc, though). It seems DocBook should 
be an ideal tool for this job.

Thanks,
		Stefan
-- 

       ...ich hab' noch einen Koffer in Berlin...