Specialized indexes

Specialized indexes
	Chapter 19. Indexes

Some document designs call for creating a specialized index, possibly in addition to a general index. A specialized index contains one category of information, such as all species mentioned in a biology book, or all function names in a programming library. Such indexes make it easier for readers to locate such specialized information.

DocBook supports the creation of specialized indexes. There are three things you have to do:

Add a type attribute to every indexterm you want to appear in a specialized index. The value of the type attribute identifies the index category.
Add an empty index element that has a type attribute whose value matches the category of indexterm elements intended for it. As with the general index, you place the empty index element in your document in the location where you want the specialized index to appear. Actually, it should not be entirely empty. You might want to add a title element as the only child of the index element, so you can give the specialized index a title that differs from the general index title.
Set the parameter index.on.type to 1. If you do not set this parameter, then the type attribute is not considered when processing index entries, and your specialized index will contain all index entries like the general index.

The following is an example of indexing on type:

Index terms:
<indexterm type="species">
  <primary>Espostoa lanata</primary></indexterm>
<indexterm>
  <primary>soil pH</primary></indexterm>
...

Index elements:
<index type="species">
  <title>Species Index</title>
</index>
<index/>

Only the first indexterm in this example will appear in the first index, whose title will be Species Index. Both entires will appear in the second index.

You can create multiple specialized indexes by using additional category names in your indexterm elements, and adding additional empty index elements for each category. However, each indexterm can have only one type value.

Note that all entries end up in the general index, the one with no type attribute on its index element. If you want to exclude the specialized entries from the general index, then you will have to add a different type attribute to all non-specialized indexterm elements, such as type="general". Then you build the general index as another specialized index by adding type="general" to its index element.

Note

If you are using version 4.2 or earlier of the DocBook DTD, then substitute role for every time you see type in the above instructions. That's because the type attribute was added in version 4.3 of the DTD, and using it in earlier versions will make the document invalid. So you would use role="species" as the attribute, and set the parameter index.on.role to 1. The stylesheets can handle either attribute.