DocBook Publishers: The Definitive Guide  (Version 1.2.1 for DocBook 5.1)

indexterm (db.indexterm.singular)

indexterm — A wrapper for an indexed term.

Synopsis

indexterm (db.indexterm.singular) ::=

Attributes

Common attributes and common linking attributes.

Additional attributes:

  • class (enumeration)
    • “singular”
  • pagenum
  • scope (enumeration)
    • “all”
    • “global”
    • “local”
  • significance (enumeration)
    • “normal”
    • “preferred”
  • type
  • zone (IDREFS)

Description

An indexterm identifies text that is to be placed in the index. In the simplest case, the placement of the indexterm in the document identifies the location of the term in the text. In other words, the indexterm is placed in the flow of the document where the index should point. In other cases, attributes on indexterm are used to identify the location of the term in the text.

An indexterm marks either a single point in the document or a range. A single point is marked with an indexterm placed in the text at the point of reference. There are two ways to identify a range of text:

  • Place an indexterm at the beginning of the range with class set to startofrange and give this term an xml:id. Place another indexterm at the end of the range with startref pointing to the xml:id of the starting indexterm. This second indexterm must be empty.

    The advantage of this method is that the range can span unbalanced element boundaries. (For example, a range could span from the middle of one paragraph to the middle of the next.)

  • Place the indexterm anywhere you like and point to the element that contains the range of text you wish to index with the zone attribute on the indexterm. Note that zone is defined as IDREFS, so a single indexterm can point to multiple ranges.

    The advantage of this method is that indexterms can be collected together or even stored totally outside the flow of the document (e.g., in the info).

Important

The common linking attributes will be removed from indexterm in DocBook V6.0. They are inappropriate for an index term.

Processing expectations

The indexterms are suppressed in the primary text flow, although they contribute to the population of an index and serve as anchors for cross-references. Under no circumstances is the actual content of indexterm rendered in the primary flow. For example, consider:

Example 5. Example index terms
<para>USB<indexterm>
<primary>USB</primary><see>Universal Serial Bus</see>
</indexterm><indexterm>
<primary>Universal Serial Bus</primary></indexterm>
and Firewire<indexterm><primary>Firewire</primary></indexterm> are
common interface technologies for external hard drives, although
eSATA<indexterm><primary>eSATA</primary><seealso>Serial ATA</seealso>
</indexterm> is also used.</para>

When rendered, either on paper or in online form, this paragraph always appears without any of the content of the index terms:

USB and Firewire are common interface technologies for external hard drives, although eSATA is also used.

For most elements, the processing expectations of an indexterm are straightforward: the location of the term serves as an anchor for the cross-reference from the index. If the word “Firewire” appears on page 75 of the document, then page 75 appears in the index entry for “Firewire”. In an online presentation, there’s an anchor for “Fireware” immediately after that word in the paragraph.

Several aspects of index markup require special attention: whitespace around index terms, “See” and “See also” entries, index markup in repeating and floating elements, and multiple indexes.

Whitespace around index terms

Special care should be taken when entering indexterms into text, especially when one of the final output formats for your document is paginated. Most processing systems are forgiving about the amount of whitespace that you use. Outside of “line-specific” environments such as literallayout, you can indent lines, insert tabs or spaces at will, and otherwise rely on the processor to coalesce multiple spaces into a single space.

However, when the processor is determining where a line or page break will occur in a long block of text, it’s an almost universal convention that such breaks occur where whitespace occurs in the markup. Sometimes words have to be hyphenated, of course, but usually it’s sufficient to break a line at a space and break a page between lines.

This means that you want to avoid extraneous spaces between index terms and the words with which they are associated. Consider this example:

<para>…long, rambling paragraph about wood ducks
<indexterm><primary>ducks</primary><secondary>wood</secondary>
</indexterm> and the habitat that they occupy, etc., etc., etc.
</para>

At first glance this seems fine, but consider what happens if the processor needs to break this paragraph across two pages. There is a small, but nonzero, chance that the page break will occur at the space (introduced by the line break) following the word “ducks”. If this happens, the anchor associated with the entry “ducks, wood” will appear on the page following the relevant words. To avoid this situation, never insert whitespace between the term and the indexterm:

<para>…long, rambling paragraph about wood
ducks<indexterm><primary>ducks</primary><secondary>wood</secondary>
</indexterm> and the habitat that they occupy, etc., etc., etc.
</para>

The whitespace after the indexterm is necessary, of course. Without it, when the indexterm is removed for presentation, the words “ducks” and “and” will appear to run together.

Index terms between block and floating elements

[PROD: BEGIN replacement material from Norm (see RT #60317, Thu Feb 18 08:04:23 2010) —Tools]

Just as extraneous whitespace can lead to indexing errors, placing index terms between block elements may lead to indexing errors.

If an index term occurs between two paragraphs, and a page break occurs between those two paragraphs, the processing system may associate the index entry with either page.

This problem can be exacerbated by floating elements. Suppose an index term appears between two figures, both of which float to subsequent pages. There is no reliable way to predict what page the processing system will associate with that index term.

If the index term in question marks the beginning or end of a range, the resulting range may contain too few, too many, or perhaps even only the wrong pages!

As a general rule, it’s best to avoid placing index terms between block elements that may be broken across multiple pages.

Index terms in repeating and floating elements

When an indexterm appears in an element whose content may be repeated in more than one place, the anchor is only associated with what would be considered the “primary” presentation (or presentations) of the element in the flow of the text. For example, in a traditional printed book, the title of a chapter might appear in the table of contents, in the running header, and in the body of the book on the first page of the chapter. If an indexterm is placed in the title, it serves as an anchor to only the first page of the chapter.

If the processing expectations of an element are that it may be repeated several times and that each of these occurrences is equally “primary,”[2] then any indexterm occurring in that element should generate an anchor at each location where the content is repeated.

If an indexterm appears in an element whose content may float, the anchor is to the location where the term occurs in the floated text. For example, if an indexterm occurs in a figure that floats to the top of some following page, the anchor is on the page where the figure actually occurs.

[PROD: END replacement material from Norm (see RT #60317, Thu Feb 18 08:04:23 2010) —Tools]

“See” and “See also” entries

The use of see and seealso elements in an indexterm also has special semantics.

A see entry directs the reader to another location in the index. In Example 5, “Example index terms”, the entry for USB:

<indexterm>
<primary>USB</primary><see>Universal Serial Bus</see>
</indexterm><indexterm>

directs the reader to the entry for Universal Serial Bus. The resulting index will look something like this:

…
Ubiquitous networking, 34, 44, 173-199
Universal Serial Bus, 50-55
Up time, 2, 5
USB, see Universal Serial Bus
Useless bits, 304, 411
…

There are no page numbers associated with a see entry. In most environments, if there is at least one see entry for a particular term, it is an error to have any other kind of entry for that term.

A seealso entry, on the other hand, directs the reader to other, possibly related terms in the index. We expect the index for “eSATA” to look something like this:

…
Entering markup, 14, 18, 22-33
eSATA, 56, 58-61
  (see also Serial ATA)
evaluating expressions, 44
…

It’s entirely possible for a term to have several seealso entries.

Multiple indexes

[PROD: Shifted <refsection> “Index terms in repeating and floating elements” was originally above this one (see RT #60317, Thu Feb 18 08:04:23 2010) —Tools]

Authors can choose to have several types of indexes: for example, function, command, and concept indexes. This can be achieved in DocBook with the type attribute. All of the indexterms with a particular type will be collected together in the index with the same type.

Attributes

Common attributes and common linking attributes.

class

Identifies the class of index term

Enumerated values:
“singular”

A singular index term

pagenum

Indicates the page on which this index term occurs in some version of the printed document

scope

Specifies the scope of the index term

Enumerated values:
“all”

All indexes

“global”

The global index (as for a combined index of a set of books)

“local”

The local index (the index for this document only)

significance

Specifies the significance of the term

Enumerated values:
“normal”

Normal

“preferred”

Preferred

type

Specifies the target index for this term

zone

Specifies the IDs of the elements to which this term applies

Parents

These elements contain indexterm: abbrev, acknowledgements, acronym, address, answer, appendix, article, artpagenums, attribution, authorinitials, bibliocoverage, bibliodiv, bibliography, biblioid, bibliolist, bibliomisc, bibliomixed, bibliomset, bibliorelation, bibliosource, blockquote, bridgehead, callout, calloutlist, caption, chapter, citation, citebiblioid, citetitle, city, colophon, confdates, confnum, confsponsor, conftitle, contractnum, contractsponsor, contrib, country, dedication, dialogue, drama, edition, email, emphasis (db._emphasis), emphasis (db.emphasis), entry, example, fax, figure, firstname, firstterm (db._firstterm), firstterm (db.firstterm), footnote, foreignphrase (db._foreignphrase), foreignphrase (db.foreignphrase), formalpara, givenname, glossary, glossdef, glossdiv, glossentry, glosslist, glosssee, glossseealso, glossterm (db._glossterm), glossterm (db.glossterm), holder, honorific, index, informalexample, informalfigure, informaltable, issuenum, itemizedlist, itermset, jobtitle, label, legalnotice, line, lineage, linegroup, link, listitem, literal, literallayout, mathphrase, member, note, olink, optional, orderedlist, orgdiv, orgname, otheraddr, othername, pagenums, para, partintro, personname, phone, phrase (db._phrase), phrase (db.phrase), pob, poetry, postcode, preface, primary, procedure, productname, productnumber, publishername, qandadiv, qandaset, question, quote (db._quote), quote (db.quote), releaseinfo, remark, result, revdescription, revnumber, revremark, secondary, section, see, seealso, seriesvolnums, setindex, shortaffil, sidebar, simpara, simplesect, state, step, street, subscript, subtitle, superscript, surname, table, taskprerequisites, taskrelated, tasksummary, term, termdef, tertiary, textobject, title, titleabbrev, toc, trademark, uri, variablelist, volumenum, wordasword, year.

Children

The following elements occur in indexterm: primary, secondary, see, seealso, tertiary.

See Also

indexterm (db.indexterm.startofrange), primary, secondary, see, seealso, tertiary

Examples

<article xmlns='http://docbook.org/ns/docbook'>
<title>Example indexterm</title>

<para>The Tiger<indexterm>
<primary>Big Cats</primary>
<secondary>Tigers</secondary></indexterm>
is a very large cat indeed.
</para>

</article>

An example of a zone.

<chapter xmlns='http://docbook.org/ns/docbook'>
<title>Example Chapter</title>

<indexterm zone="a1"><primary>Network Configuration</primary></indexterm>

<!-- other content here -->

<section xml:id="a1"><title>Configuring Your Network</title>
<para>…</para>
</section>

</chapter>



[2] 

No elements in DocBook V5.0 have these semantics.