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
<indexterm> element without the
@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
(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.
<indexterm> that occurs in a topic
interpreted as a point reference to the title of the topic. Likewise, in a DITA map, an
<indexterm> that occurs in
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
<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 are domain specializations of the
<index-base>element, and are discussed in detail with the indexing domain.
@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.
<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
ancestors; however, an implementation should be able to handle an end-of-range
<indexterm> that is nested within one or more
@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
@end attributes is done as a
character-by-character comparison with all characters significant and no case folding
@end attributes are ignored if
they occur on an
<indexterm> element that has child
<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.
See appendix for information about this element in OASIS document type shells.