| DocBook: The Definitive Guide 2.0.12 (Alpha)

# indexterm

$Revision: 1.5 $

$Date: 2005/04/15 13:17:22 $

indexterm — A wrapper for terms to be indexed

## Synopsis

### Content Model

    indexterm ::=
    (primary?,
     ((secondary,
       ((tertiary,
         (see|seealso+)?)|
        see|seealso+)?)|
      see|seealso+)?)

### Attributes

Common attributes

Name | Type | Default
significance |
Enumeration:
normal
preferred
| "normal"
zone | IDREFS | None
pagenum | CDATA | None
scope |
Enumeration:
all
global
local
| None
type | CDATA | None
startref | IDREF | None
class |
Enumeration:
endofrange
singular
startofrange
| None

## Description

`IndexTerm`s identify 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 at the point where the `IndexEntry` in the `Index` should point. In other cases, attributes on `IndexTerm` are used to identify the location of the term in the text.

`IndexTerm`s mark 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 `ID`. Place another `IndexTerm` at the end of the range with `StartRef` pointing to the `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.

- 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 `IndexTerm`s can be collected together or even stored totally outside the flow of the document (in the meta for example).

### Processing expectations

`IndexTerm`s 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.

It is possible to construct index terms that are difficult to parse at best and totally illogical at worst. Consider the following:

    <indexterm class='startofrange' zone="id1 id2">...</indexterm>

There is no way that this can fit into the semantics of an `IndexTerm`. Although it claims to be the start of a range, it does not have an `ID` for the end-of-range `IndexTerm` to point back to. In addition, it includes zoned terms, and mixing the two different methods for indicating a range in the same `IndexTerm` is probably a bad idea.

### Parents

These elements contain indexterm: `abbrev`, `accel`, `ackno`, `acronym`, `action`, `answer`, `appendix`, `appendixinfo`, `application`, `article`, `articleinfo`, `artpagenums`, `attribution`, `authorinitials`, `bibliocoverage`, `bibliodiv`, `biblioentry`, `bibliography`, `bibliographyinfo`, `biblioid`, `bibliomisc`, `bibliomixed`, `bibliomset`, `bibliorelation`, `biblioset`, `bibliosource`, `blockinfo`, `blockquote`, `bookinfo`, `bridgehead`, `callout`, `caution`, `chapter`, `chapterinfo`, `citation`, `citebiblioid`, `citetitle`, `city`, `classname`, `classsynopsisinfo`, `code`, `collabname`, `command`, `computeroutput`, `confdates`, `confnum`, `confsponsor`, `conftitle`, `constant`, `constraintdef`, `contractnum`, `contractsponsor`, `contrib`, `corpauthor`, `corpcredit`, `corpname`, `country`, `database`, `date`, `dedication`, `edition`, `email`, `emphasis`, `entry`, `envar`, `errorcode`, `errorname`, `errortext`, `errortype`, `example`, `exceptionname`, `fax`, `figure`, `filename`, `firstname`, `firstterm`, `foreignphrase`, `formalpara`, `funcparams`, `funcsynopsisinfo`, `function`, `glossary`, `glossaryinfo`, `glossdef`, `glossdiv`, `glossentry`, `glosssee`, `glossseealso`, `glossterm`, `guibutton`, `guiicon`, `guilabel`, `guimenu`, `guimenuitem`, `guisubmenu`, `hardware`, `highlights`, `holder`, `honorific`, `important`, `index`, `indexinfo`, `informalexample`, `informalfigure`, `initializer`, `interface`, `interfacename`, `invpartnumber`, `isbn`, `issn`, `issuenum`, `itemizedlist`, `itermset`, `jobtitle`, `keycap`, `keycode`, `keysym`, `label`, `legalnotice`, `lineage`, `lineannotation`, `link`, `listitem`, `literal`, `literallayout`, `lotentry`, `manvolnum`, `markup`, `medialabel`, `member`, `methodname`, `modespec`, `modifier`, `mousebutton`, `msgaud`, `msgexplan`, `msglevel`, `msgorig`, `msgtext`, `note`, `objectinfo`, `olink`, `option`, `optional`, `orderedlist`, `orgdiv`, `orgname`, `otheraddr`, `othername`, `package`, `pagenums`, `para`, `parameter`, `partinfo`, `partintro`, `phone`, `phrase`, `pob`, `postcode`, `preface`, `prefaceinfo`, `procedure`, `productname`, `productnumber`, `programlisting`, `prompt`, `property`, `pubdate`, `publishername`, `pubsnumber`, `qandadiv`, `qandaset`, `question`, `quote`, `refentry`, `refentryinfo`, `refentrytitle`, `referenceinfo`, `refmeta`, `refmiscinfo`, `refpurpose`, `refsect1`, `refsect1info`, `refsect2`, `refsect2info`, `refsect3`, `refsect3info`, `refsection`, `refsectioninfo`, `refsynopsisdiv`, `refsynopsisdivinfo`, `releaseinfo`, `remark`, `returnvalue`, `revdescription`, `revnumber`, `revremark`, `screen`, `screeninfo`, `sect1`, `sect1info`, `sect2`, `sect2info`, `sect3`, `sect3info`, `sect4`, `sect4info`, `sect5`, `sect5info`, `section`, `sectioninfo`, `seg`, `segtitle`, `seriesvolnums`, `setindex`, `setindexinfo`, `setinfo`, `sgmltag`, `shortaffil`, `sidebar`, `sidebarinfo`, `simpara`, `simplesect`, `state`, `step`, `street`, `structfield`, `structname`, `subtitle`, `surname`, `symbol`, `synopsis`, `systemitem`, `table`, `task`, `taskprerequisites`, `taskrelated`, `tasksummary`, `td`, `term`, `th`, `tip`, `title`, `titleabbrev`, `tocback`, `tocentry`, `tocfront`, `token`, `type`, `ulink`, `uri`, `userinput`, `variablelist`, `varname`, `volumenum`, `warning`, `wordasword`, `year`.

### Children

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

## Attributes

class

  `Class` identifies the type of `IndexTerm`. If `StartRef` is supplied, the default for `Class` is `EndOfRange`, otherwise it is `Singular`.

pagenum

  `PageNum` indicates the page on which this index term occurs in some version of the printed document.

scope

  `Scope` identifies in which indexes the `IndexTerm` should appear. `Global` means the index for the whole collection of documents, `Local` means the index for this document only, and `All` means both indexes.

significance

  `Significance` specifies whether or not this `IndexTerm` is considered the most important location for information about the terms being indexed. Generally, `Preferred` `IndexTerm`s get special typographic treatment in the `Index`.

startref

  The use of `StartRef` implies a spanning index entry. `StartRef` is used on the term that defines the end of the span and points to the term which defines the beginning.

type

  FIXME:

zone

  The use of `Zone` implies a spanning index entry. `Zone` holds the IDs of the elements to which it applies. The `IndexTerm` applies to the contents of the entire element(s) to which it points. If `Zone` is used, the physical placement of the `IndexTerm` in the flow of the document is irrelevant.

## See Also

`indexentry`, `primary`, `primaryie`, `secondary`, `secondaryie`, `see`, `seealso`, `seealsoie`, `seeie`, `tertiary`, `tertiaryie`.

## Examples

    <!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <para>
    The Tiger<indexterm>
    <primary>Big Cats</primary>
    <secondary>Tigers</secondary></indexterm>
    is a very large cat indeed.
    </para>

The Tiger is a very large cat indeed.

    <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <chapter><title>Example Chapter</title>

    <!-- index term for "Example Chapter" is a span -->
    <indexterm id="idxexchap" class='startofrange'>
      <primary>Example Chapter</primary></indexterm>

    <!-- index term for "Example Chapter" also cross references the
         "Examples" entry in the index -->
    <indexterm><primary>Example Chapter</primary>
      <seealso>Examples</seealso></indexterm>

    <!-- index term for "Chapter, Example" refers the reader to the entry
         under which the index term is actually listed, "Example Chapter" -->
    <indexterm><primary>Chapter</primary><secondary>Example</secondary>
      <see>Example Chapter</see></indexterm>

    <!-- other content -->

    <!-- index term, end of "Example Chapter" span -->
    <indexterm startref="idxexchap" class="endofrange"/>

    <para>some content</para>
    </chapter>

    <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
              "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    <chapter><title>Example Chapter</title>
    <indexterm zone="a1"><primary>Network Configuration</primary></indexterm>
    <!-- other content here -->
    <sect1 id="a1"><title>Configuring Your Network</title>
    <para>&hellip;</para>
    </sect1>
    </chapter>

For additional examples, see also `chapter`.

indexinfo |  | informalequation

Copyright © 1999, 2000, 2001, 2002, 2003 O'Reilly & Associates, Inc. All rights reserved.