Indexing in DocBook XML

Docbook XML provides the basic capability for creating back-of-the-book style indexes. Specific indexing features of DocBook XML are:

  • main headings, subheadings and sub-sub headings
  • "See" and "See also" cross-reference
  • page ranges
  • customized sorting for individual index entries

The DocBook document type definition (DTD) was developed to provide an application independent method for creating computer documentation. Versions of the DocBook DTD have been created for both SGML and XML.

You can create an embedded index in DocBook using index elements. For example, to enter the main heading “tape backup” you would enter the following:

<indexterm><primary>tape backup</primary></indexterm>

The whole index entry is enclosed within the “indexterm” element with <indexterm> indicating the start of the index entry and </indexterm> indicating the end of the index entry. The “primary” element indicates the main index heading.

Within the DocBook indexterm element you can also specify an optional ID for that index entry, for example:

<indexterm id="tape backup"><primary> tape backup</primary></indexterm>

To specify a subheading, you simply add a “secondary” index element, for example:

<indexterm><primary>paper jams</primary><secondary>fixing</secondary></indexterm>

To specify a range, you need to enter a DocBook indexterm element at the start of the range and another indexterm element to mark the end of the range. The indexterm ID is required when specifying a range:

<indexterm id="A1" class="startofrange"><primary>Internet</primary></indexterm>

<indexterm startref="A1" class="endofrange">

“See” and “See also” cross-references can be entered as follows:

<indexterm><primary>art</primary><see>graphics</see></indexterm>

<indexterm><primary>cable</primary><seealso>wiring</seealso></indexterm>

Note that unlike most other publishing systems, “See also” cross-references in DocBook must be associated with a regular index entry.

To produce the final DocBook XML index, you will need to use special software to generate the index and to format it. Be sure to test the software beforehand to make sure it handles the different types of index entries correctly.

By embedding the index in a DocBook XML document, you will be able to automatically update the index when the document is revised.

Fred Brown
Allegro Technical Indexing
fred.brown@allegrotechindexing.com
(613) 728-9373

September, 2001; Updated: May, 2009
Allegro Time!


Home | Website indexing | Training | Professional expertise | Articles
Test your index | Sample indexes | Internet links | Contact Allegro