Number of columns.
Typography of titles.
Typography of index entries.
Punctuation of index entries.
Remove duplicate page numbers using extensions.
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
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
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>
|Description||Default value||Gentext template name||Parameter name|
|Separator between the end of an index term's text and its first page number.||Comma and space.|
|Separator between two page numbers.||Comma and space.|
|Separator between the numbers in a page range.||Dash.|
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
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.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises