indexterm

Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition

Document
Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition
Version
1.3
Author
OASIS DITA Technical Committee

The content of an indexterm element is used to produce an index entry in a generated index. You can nest indexterm elements to create multi-level indexes. The content is not output as part of the topic content, only as part of an index.

An indexterm element without the start or end attribute specified is interpreted as a point reference that contributes the number of the current page to an index entry; the content of the index entry is the content of the indexterm element. All indexterm elements with the same content are "merged" to form a single index entry in the resulting index, and all contributed page numbers are included in that index entry.

In the case of nested indexterm elements, each indexterm with no indexterm children (the "leaves") contributes a page number to the generated index; the ancestral indexterm elements for each leaf indexterm provide the higher levels for the multilevel entry.

An indexterm that occurs in a topic prolog is interpreted as a point reference to the title of the topic. Likewise, in a DITA map, an indexterm that occurs in topicmeta inside of a topicref is interpreted as a point reference to the title of the referenced topic.

It is an error if an indexterm containing no indexterm children contains both an index-see and an index-see-also. (Note: index-see and index-see-also elements within indexterm elements that do contain indexterm children are ignored.) In the case of this error condition, an implementation MAY give an error message, and might recover by treating all such index-see elements as index-see-also elements.

Note: The index-see and index-see-also elements are domain specializations of the index-base element, and are discussed in detail with the indexing domain.

The start and end attribute on indexterm can be used in cases where one wants to index an extended discussion that might continue over a number of pages. The start of a range is indicated by an indexterm with a start attribute. The end of a range is indicated with an indexterm with an end attribute whose value matches that of the start attribute on the start-of-range indexterm. Such markup contributes to the generated index a page range covering all pages in the index range.

The end-of-range indexterm should have no content of its own; if it contains content, that content is ignored. There is no reason for the end-of-range indexterm to have any indexterm ancestors; however, an implementation should be able to handle an end-of-range indexterm that is nested within one or more indexterm elements.

The start and end attributes are defined as CDATA, although it is a best practice that the values should not contain any whitespace characters (such as a space or tab) or control characters. Matching of start and end attributes is done as a character-by-character comparison with all characters significant and no case folding occurring. The start and end attributes are ignored if they occur on an indexterm element that has child indexterm elements.

Index range indications can occur in the topicmeta of a topicref at the map level, in the prolog of a topic, or in the body of a topic, and are interpreted as follows (see Figure 3 for samples):
  • In a map, the start range points to the start of the topic title of the topic being referenced by its containing topicref. The end range points to the end of the final child contained by the topic being referenced by its containing topicref, or to the end of the final topic referenced by the current map (whichever comes first). When a start and end range occur in the same topicmeta, the range applies to the containing topicref and its children.
  • In the prolog of a topic, the start range points to the start of the containing topic's title. The range ends with a matching index range end in the same prolog, regardless of whether the end range is specified. The range applies to the containing topic and all its children including child relationships defined in a map.
  • In the body of a topic, the range starts where the start indexterm occurs and ends at the matching index range end indication within the same body, or at the end of the body, whichever comes first. Such an index range does not span sub-topics of the topic.

When index ranges with the same identifier overlap, the widest range applies, and end ranges are matched with start ranges by last-in-first-out. In other words, the ranges are interpreted as nested rather than overlapping with the highest-level container taking precedence over narrower contained ranges.

As defined above, there is no such thing as an index range start that isn't terminated by either a matching end or some maximum scope. There can, however, be unmatched index range end indications; these are ignored.

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

- topic/indexterm

Example

Figure. Single point index terms
  • The following indexterm is a point reference to a specific paragraph within a topic:
    <p><indexterm>databases</indexterm>Databases are used to ...</p>
  • The following indexterm is a point reference to the start of the title of the concept:
    <concept id="db">
      <title>About databases</title>
      <prolog>
        <metadata>
          <keywords><indexterm>databases</indexterm></keywords>
        </metadata>
      </prolog>
      <body><!-- content... --></body>
    </concept>
  • The following indexterm is a point reference to the start of the title of aboutdatabases.dita:
    <topicref href="aboutdatabases.dita">
      <topicmeta>
        <keywords><indexterm>databases</indexterm></keywords>
      </topicmeta>
      <!-- other topicref elements -->
    </topicref>
Figure. Nested index terms
The following sample represents three levels of index markup:
<indexterm>cheese
  <indexterm>sheeps milk
    <indexterm>pecorino</indexterm>
  </indexterm>
  <indexterm>goats milk
    <indexterm>chevre</indexterm>
  </indexterm>
</indexterm>
The previous sample is equivalent to the following sample:
<indexterm>cheese
  <indexterm>sheeps milk
    <indexterm>pecorino</indexterm>
  </indexterm>
</indexterm>
<indexterm>cheese
  <indexterm>goats milk
    <indexterm>chevre</indexterm>
  </indexterm>
</indexterm>
In each case, a generated index would include something like the this:
  • cheese
    • goats milk
      • chevre 14
    • sheeps milk
      • pecorino 14
Figure. Index ranges
A simple index range will look something like this:
<indexterm start="cheese">Cheese</indexterm>
<!-- ... additional content -->
<indexterm end="cheese"/>
The previous combination of terms will generate a top-level index term for "Cheese" that covers a series of pages, such as:
  • Cheese 18-24
Specifying a range for nested terms is similar. In this sample, the range is specified for the tertiary index entry "pecorino":
<indexterm>cheese
  <indexterm>sheeps milk
    <indexterm start="level-3-pecorino">pecorino</indexterm>
  </indexterm>
</indexterm>
 <!-- ... additional content ... -->
<indexterm end="level-3-pecorino"/>
The generated index for that range would look something like this:
  • cheese
    • sheeps milk
      • pecorino 18-24

There are three locations that can declare a range - the body of a topic, the prolog of a topic, and a map.

  • In the following example, the range begins at the start of the second paragraph, and continues to the last paragraph. If the matching end range was not included, the range would end at the end of the body element.
    <topic id="accounting">
      <title>Accounting regulations</title>
      <body>
        <p>Be ethical in your accounting.</p>
        <p><indexterm start="acctrules">Rules</indexterm>Remember to do all of the following: ...</p>
        <!-- ...pages worth of rules... -->
        <p><indexterm end="acctrules"/>Failure to comply will get you audited.</p>
      </body>
      <!-- Potential sub-topics -->
    </topic>
  • In the following example, the range begins with the start of the topic's title, and covers the entire topic and any sub-topics. The range ends within the same prolog, regardless of whether <indexterm end="acct"/> is specified in the prolog.
    <topic id="accounting">
      <title>Accounting rugulations</title>
      <prolog>
        <metadata>
          <keywords><indexterm start="acct">Accounting</indexterm></keywords>
        </metadata>
      </prolog>
      <!-- Body and sub-topics -->
    </topic>
  • Now assume that the topic in the previous sample is named acct.dita. Ranges defined in a prolog cover sub-topics, including those nested based on a map; in the following example, this means that the range covers all of acct.dita, as well as procedures.dita and forms.dita:
    <topicref href="acct.dita">
      <topicref href="procedures.dita"/>
      <topicref href="forms.dita"/>
    </topicref>
  • In the final example, the range is specified in a map. The index range for "Accounting" begins with the start of the first topic title in acct.dita, and covers that file as well as any sub-topics. The index range for "Government forms" begins with the start of the first topic title in acct.dita, and continues until the end of the last element in the file taxfiling.dita. If the end range for "govt" was not specified, the range would continue to the end of the map.
    <topicref href="acct.dita">
      <topicmeta>
        <keywords>
          <indexterm start="acct">Accounting</indexterm>
          <indexterm end="acct"/>
          <indexterm start="govt">Government forms</indexterm>
        </keywords>
      </topicmeta>
      <!-- Nested topicref elements -->
    </topicref>
    <topicref href="taxfiling.dita">
      <topicmeta>
        <keywords>
          <indexterm end="govt"/>
        </keywords>
      </topicmeta>
    </topicref>
Figure. Index term with ph or ph specializations
<p>Einstein's most famous equation
E=mc<sup>2</sup><indexterm>E=mc<sup>2</sup></indexterm> 
expresses the relationship between mass and energy.</p>

All the elements in the highlighting domain are specializations of ph.

Attributes

The following attributes are available on this element: Universal attribute group, keyref, and the attributes defined below.

start
Specifies that an index entry is positioned at the beginning of a range. The value matches the end attribute on another indexterm.
end
Specifies that an index entry is positioned at the end of a range; value matches the start attribute on another indexterm.