DOCBOOK-APPS: Re: DOCBOOK: Reference documentation

[Bob McIlvride <robert at cogent dot ca>]

Hi Morten,

The simple answer is to wrap your <refentry>'s in a <reference> element. 
Switching on the correct parameters in the stylesheet should generate a TOC 
page in front of all the refentry pages that has a list like you need.

This is fine for maybe 30 or 40 reference entries.   If you have a few 
hundred, you might wish to break them up into categories, using several 
<reference> elements.  Then you'll get a nice TOC for each category.  You 
can even put the <reference> elements into a <part> to get a TOC of them.

You can see what I'm talking about here:
http://developers.cogentrts.com/cogent/cogentdocs/gm-reference.html

However, you don't get one central alphabatized list.  If you index each 
refentry, and generate an index, that gives you a complete list, but it will 
be combined with all the other index entries.

We have a manual that documents a language with about 300 ref entries, and 
we have followed these steps, but we've gone one further.  Most of our 
refentries document built-in functions, sometimes with 2 or 3 functions per 
entry.  Our programmers demanded an alphabetized list of every function, and 
we finally had to write one by hand (well, using emacs macros, but we 
maintain and update it by hand).   So I guess that's the long answer.

The hand-maintained list is here:
http://developers.cogentrts.com/cogent/cogentdocs/gm-ax-functionlist.html

Keeping track of all this is quite a project.  We do it with entity files. 
  There is a brief explanation of this here:
http://developers.cogentrts.com/cogent/prepdoc/pd-referenceentriesandsections.html

Hope that helps.  Have fun!

Bob

---------------------------------------
Robert McIlvride (robert@cogent.ca)
Cogent Real-Time Systems (www.cogent.ca)