Re: [docbook-apps] Indexing.

["John W. Shipman" <john@nmt.edu>]

I've indexed three 500-page books, but never in DocBook.
However, I'd like to reinforce Thomas Schraitle's point that it
is both important and nontrivial.

The first thing I'd recommend is to read up on indexing.  The
Wikipedia page is a good starting point.

    http://en.wikipedia.org/wiki/Index_%28publishing%29

In earlier eras I used the "Chicago Manual of Style" to learn
about good practices.

There are certain very specific fetishes I have about indexing
that I see violated quite often.

The index to the "Guide to LaTeX" by Helmut Kopka has an example
of a horrible flaw that severely compromises its usefulness:
if a major topic is continued over a page break, the major
topic is NOT repeated on the continuation column.

Think about how you use an index: you depend on the top words
of each column to be in alphabetical order.  But on page
584 of Kopka's book, the entire column is a continuation of
major topic "package", but the first entry is "amsmath".
So you think you're in the "a" section of the index, but you're
actually in the "p" section!

It should look like this, but in many books I don't see a
line like the first one:

    package (continued)
        amsmath, 191, 269-270
        amsopn, ...

An obvious application for marks.

My next suggestion may slightly increase the page count, so I
never mentioned it back in the day when dead trees were the
only route to publication.  However, the increase is small,
and inexcusable if you expect most people will e-read your
book.

As an example, the discussion of the amsmath package should
have two entries:

    amsmath package, 372
    packages, 366
        amsmath, 372

In general, if an indexable phrase has more than one important
word, it should appear in the index under each of those words.

I can't give you any useful suggestions on current tools.  Back
in the day I just invented a file format for entering all the
indexable references and then wrote my own software in C to
generate the index in TeX.  This approach assumes that the
page numbers are all cast in stone, which was fine because
in my cases the rest of the book had all been put to bed.

Best regards,
John Shipman (john@nmt.edu), Applications Specialist, NM Tech Computer Center,
Speare 146, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john
  ``Let's go outside and commiserate with nature.''  --Dave Farber