Re: [docbook] Automatically create index of commands

[Bob Stayton <bobs at sco dot com>]

On Thu, Aug 28, 2003 at 10:05:20AM +0200, David N. Welton wrote:
> davidw@dedasys.com (David N. Welton) writes:
> 
> > Hrm... I had really hoped to get an index on the same page as the
> > commands.  I don't have enough, yet, to break them all out into
> > separate pages.  Is the ref stuff still appropriate in that case?
> 
> Apparently not - it doesn't output anything when contained in a
> section.
> 
> > In any case I'm pretty sure I also want the index either on the same
> > page or a second page, but not in the table of contents.  I guess
> > it's time to start hitting the XSL file.
> 
> .. with which I've had a little bit of success.  But I'm still not
> sure what the appropriate elements are to make the index with.  I need
> a name and a short description, akin to refpurpose, that will not be
> printed along with the 'main' cmdsynopsis.
> 
> indexterm doesn't look right...  I'm stumped.

Ever since HTML started using "index.html"
to mean a table of contents, I've been confused.  8^)
Just to be perfectly clear here,
when you say "index", you mean a listing of entries
at the beginning of the section containing the entries?  
Not a back-of-the-book index, right?

If so, then you can do this with the HTML stylesheets
out of the box.  The TOC mechanism has a lot of
options, and I think it can meet your needs.

Rewrite your entries from varlistentry
to refentry as Bob sugggested.  That gives you the
structure for name and purpose for each entry.
You can put a set of refentry elements in a sect1 or
other section level, without putting them into a reference
container.  What's missing is a section table of contents,
which you need to turn on using this stylesheet parameter:

generate.section.toc.level=1  (if you use sect1)

This turns on a table of contents for sect1 level
elements.  Of course, it will turn on the toc
for all sect1 level elements, which you may
not want.  There are ways to work around that
if you are interested.

The TOC for the section will include a line for
each refentry element.  Since the 'annotate.toc'
stylesheet parameter is set to 1 by default, it
will add the refpurpose to each TOC entry.

Do you also want this for print output?  If so,
you need to also modify the 'generate.toc' parameter
to enable a toc for the appropriate section level.
Then the generate.section.toc.level can turn it on.

-- 


Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com

To unsubscribe from this list, send a post to docbook-unsubscribe@lists.oasis-open.org.