Index

Features for formatting and styling a back-of-book index

Display graphics for index

The <index> element is used to produce a back-of-book index. An index can be produced automatically from embedded index terms in chapters and other book components (e.g. preface, appendix). To produce an index in this way, you need to be generally familiar with the indexing functions of DocBook XML (references to online resources are below). The <index> element can contain a title and other descriptive text in <para> tags, but otherwise it is empty (i.e. no other tags are required).

There are embedded index terms throughout the example XML templates you can follow. The main element to define each index term is <indexterm>. Nested within <indexterm> is a <primary> element (to specify text for main headings), and optionally <secondary> (to specify text for subheadings) and <tertiary> (to specify text for subsubheadings) elements. Any text typed inside those three nested elements appears only in the index. For technical reference, read the publication DocBook XSL: The Complete Guide.

The stylesheets p14-endmatter.xsl and c1-commonstyles.xsl have all features and instructions to set up styles for an index.

The index formats that can be set in the stylesheet p14-endmatter.xsl are:
The index formats that can be set in the stylesheet c1-commonstyles.xsl are:

XML markup to edit

Index naming. You should give the <index> element a unique xml:id value, such as "endindex". This is because when you produce EPUB and web pages, an HTML file called "index.html" is generated for the home page (title page) of the ebook. You need to differentiate the name of that page from the name of the back-of-book index page, so by giving the <index> element an ID name, it will be generated as a separate web page.

Note: If you do not add an ID name to the <index> element, it might not generate as a HTML file. The home page of the ebook is called "index.html" and this will overwrite a back-of-book index with the same name.

Index ranges. If there is a specific index term that occurs in several subsequent sections of a document, then it is likely to span across pages in an output PDF. The output result of these index terms would be sequential page numbers in the index for that term, such as: 3, 4, 5, 6. Instead of leaving all the individual <indexterm> elements in each section, you can specify one <indexterm> element as the starting point and another <indexterm> as the ending point. The result in the index would be the starting and ending page numbers with a dash, such as 3–6 (set the dash punctuation at stylesheet feature c1-365). Both <indexterm> elements must have the same ID value for the index range to work.

The starting <indexterm> has the class attribute value "startofrange", an xml:id value and a nested <primary> element with the index term. For example:
<indexterm class="startofrange" xml:id="informalfigure"> <primary>informalfigure element </primary> </indexterm>
The ending <indexterm> element is an empty tag—it does not have any index term text inside. The class attribute value is "endofrange", and the startref attribute must have the same name as the xml:id value in the starting <indexterm>. For example:
<indexterm class="endofrange" startref="informalfigure"/>
For technical reference see http://www.sagehill.net/docbookxsl/GenerateIndex.html#Indexterms.

Preferred pages. You can have specific page numbers highlighted in the output index as preferred pages. This is useful, for example, for highlighting to the reader page numbers in bold text that cover the main discussion of a specific topic. Alternatively, preferred page numbering can be used to highlight page numbers that refer to figures, so as to distinguish index entries for figures apart from entries for body text.

The indexterm has the attribute significance with the value "preferred". For example:
<indexterm significance="preferred"> <primary>text...</primary> </indexterm>
For technical reference see http://www.sagehill.net/docbookxsl/FormatPrintIndex.html#FormatIndexEntry.
Subject indexes. As well as a general index that contains all embedded index terms, you can generate specialised subject indexes (as a subset of the general index) containing terms that relate to a topic. For example, you can generate a subject index containing people's names. First you need to create an empty <index> XML file with similar tagging as for a general index. The <index> element must have the type attribute with any value (name) that identifies the broad index topic. For example, an <index> element that contains people's names can be:
<index type="people">
To specify what index terms in the body text will appear in the subject index, specify the type attribute with the same value as the subject index. For example:
<indexterm type="people"> <primary>Einstein</primary> </indexterm>

Then switch on the subject-specific index function at stylesheet feature c1-345. When you produce an ebook, a second index with those terms will be generated.

For technical reference see http://www.sagehill.net/docbookxsl/IndexSpecial.html.

Stylesheet settings to edit

The relevant Stylesheet Guide page to set up index formats is PDF-index.svg.