The stock format for DocBook indexes is two columns with a 12pt column separation. These features are controlled by the column.count.index parameter and the column.gap.index parameter, respectively. If you set the column.count.index parameter to 3, for example, your print index will have three columns per page.

The titles in a print index include the main index title, and the titles for the letter subdivisions. The main title is controlled by the titlepage specifications file that generates titlepage templates. See the section “Title page spec file” to learn how to customize the titlepage specs and generate new templates. The main title is controlled by the specifications for t:element="index".

The letter subdivision titles in an index are controlled by the index.div.title.properties attribute-set (starting with version 1.68). Attributes defined in that attribute-set are applied to the fo:block containing the title, so you can specify the font family, style, and weight, as well as spacing above and below.

Index titles in HTML output can be formatted using CSS styles. Peek in the HTML output to see the class attributes that are used, and create CSS selectors to handle them.

You can change the way index entries format by using the index.entry.properties attribute-set, introduced in version 1.68 of the stylesheets. That attribute-set is applied to the block containing each index entry. By default, this attribute-set is empty. The most common change is to reduce the type size and line spacing so the index uses fewer pages:

<xsl:attribute-set name="index.entry.properties">
  <xsl:attribute name="font-size">8pt</xsl:attribute>
  <xsl:attribute name="line-height">8pt</xsl:attribute>
</xsl:attribute-set>

Another attribute-set is available to add styles to the page numbers presented in a printed index. Any attributes defined in the index.page.number.properties attribute-set (introduced in stylesheet version 1.72) will be added to the fo:basic-link element that wraps around each generated page number reference. You can use that to change the color to indicate that the page number is a clickable link in the PDF file.

<xsl:attribute-set name="index.page.number.properties">
  <xsl:attribute name="color">blue</xsl:attribute>
</xsl:attribute-set>

If you are using XEP, any attributes defined in index.page.number.properties are also used in the xep.index.item.properties attribute-set, so that they are applied to the page numbers generated in the XEP XSL-FO processor using its indexing extensions.

You can also control the typography of the preferred page number if you use that feature. Preferred page numbers are designated by putting significance="preferred" attributes on selected indexterm entries in your document. The page numbers for such preferred references are formatted using the index.preferred.page.properties attribute-set. By default, that attribute-set changes such page numbers to bold. You can change that to italic by adding this to your customization layer:

<xsl:attribute-set name="index.preferred.page.properties">
  <xsl:attribute name="font-weight">normal</xsl:attribute>
  <xsl:attribute name="font-style">italic</xsl:attribute>
</xsl:attribute-set>

You can also control the punctuation used in index entries, if you must meet style requirements or locale conventions. By default the stylesheet automatically inserts the following punctuation:

As the last column in the table shows, there are parameters that are available to control the punctuation. However, those exist for convenience and are empty by default in the stylesheet. That's because punctuation differs by language and locale, so a single parameter value would not suffice.

The default values are set using the gentext template names shown in the above table. They are in a context element with name="index" in each locale's gentext file such as common/en.xml. See the section “Generated text” to see how to change the values for different locales.

The parameters shown in the table will override the corresponding gentext value. You can use the parameters for convenience if you are processing documents in a single language that uses one style of punctuation.

There are a few problems in generating page numbers in a print index that an XSL stylesheet cannot solve. The basic problem is that the stylesheet does not know what page number a given index entry will generate, so all it can do is output a page reference for each entry. But if two or more copies of the same index entry happen to land on the same page, then the index will repeat the page numbers. Also, most indexes collapse a consecutive sequence of page numbers for an entry into a page range, but the stylesheet cannot know which page references will be in a sequence.

To solve these problems and improve the quality of printed indexes, most XSL-FO processors provide indexing extensions. These extensions can eliminate duplicate page references in an entry, and collapse a sequence into a range. The DocBook XSL stylesheets use these extensions when the appropriate processor parameter is set.

XSL Formatter from Antenna House supports an index extension attribute to remove duplicate page numbers in an entry. This attribute is output by DocBook XSL when the stylesheet parameter axf.extensions="1":

<xsl:attribute name="axf:suppress-duplicate-page-number">true</xsl:attribute>

The XEP processor from RenderX takes a more comprehesive approach to indexing. You can activate its extensions in DocBook XSL by setting the stylesheet parameter xep.extensions="1". XEP first defines its own extension attribute (rx:key) to use in place of id as an index marker. The key value is the text of the indexterm element. Then XEP defines two extension elements. The rx:index-item is used once for all entries that match, and it uses its ref-key attribute to match key values anywhere in the document's output. XEP's other extension element rx:page-index is used to specify some formatting properties and to contain the rx:index-item element. When processing an rx:index-item, the processor locates the page numbers for all the rx:key properties that match, and then generates the string of numbers with duplicates removed and sequences collapsed into page ranges. See the XEP documentation for more details.

The index generating templates in the DocBook stylesheets are among the most complex in the whole set. They use every method and trick to gather, sort, group, and present the output in a usable index. Customizing the index templates requires careful study of the existing templates to learn how they work.

You can learn more about the DocBook indexing templates from a paper published by Jirka Kosek titled Using XSLT for getting back-of-the-book indexes.