Indexterm

An <indexterm> element allows the author to indicate that a certain word or phrase should produce an index entry in the generated index.

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

An <indexterm> element (with no start or end attribute specified) is interpreted as a point reference that will contribute the number of the current page to an index entry whose contents is the content of the indexterm. All indexterms 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 indexterms, the indexterms with no indexterm children (i.e., the "leaves") each contribute a page number to the generated index; the ancestral indexterm elements for each leaf indexterm provide the higher levels for the multilevel entry for which the leaf indexterm is the lowest level.

An indexterm that occurs in a topic prolog is interpreted as a point reference to the start of the title of the 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 indexterms that do contain indexterm children are ignored.) In the case of this error condition, an implementation may (but need not) give an error message, and may (but need not) recover by treating all such index-see elements as index-see-also elements.

The start and end attribute on indexterm can be used in cases where one wishes to index an extended discussion that may 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 would contribute 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; any content it has 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 nested within one or more indexterms.

The start and end attributes are defined as CDATA, though it is recommended that the values should not contain any whitespace characters (e.g., space, 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 unless they occur on an indexterm element that has no child indexterm elements (i.e., a leaf indexterm).

Index range

indications may 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:

• 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 a prolog, 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, or the end of the prolog, whichever comes first. The range applies to the containing topic and all its children including child relationships defined in a map.
• In a body, 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 should be ignored.

[edit] Example

<p>An indexterm element allows the author to indicate that
a certain word or phrase should produce an index entry in the
generated index. You can nest indexterm elements to create
multi-level indexes.<indexterm>indexterm</indexterm>
<indexterm>Valid in Many Places elements<indexterm>indexterm</indexterm>

</indexterm></p>

Markup such as 

<indexterm>cheese
  <indexterm>sheeps milk
    <indexterm>pecorino</indexterm>
  </indexterm>
  <indexterm>goats milk
    <indexterm>chevre</indexterm>

  </indexterm>
</indexterm>

would be equivalent to

<indexterm>cheese
  <indexterm>sheeps milk
    <indexterm>pecorino</indexterm>
  </indexterm>

</indexterm>
<indexterm>cheese
  <indexterm>goats milk
    <indexterm>chevre</indexterm>
  </indexterm>
</indexterm>

and would be part of the input that might generate resulting index entries such as

• cheese
  • goats milk
    • chevre 14
• • sheeps milk
    • pecorino 14

 Markup such as 

<indexterm>cheese
  <indexterm>sheeps milk
    <indexterm start="level-3-pecorino">pecorino</indexterm>

  </indexterm>
</indexterm>
 . . .
<indexterm end="level-3-pecorino"/>

(where the ellipses represent several pages worth of input) might generate an index entry such as

• cheese
  • sheeps milk
    • pecorino 18-24

[edit] Contains

text data  or keyword or option or parmname or apiname or cmdname or msgnum or varname or wintitle or term or data or data-about or foreign or unknown or 

text data  or keyword or term or data or data-about or foreign or unknown or 

[edit] Contained by

[edit] Inheritance:

- topic/indexterm

[edit] Attributes

TOC: Language Specification 1.1
Parent topic: Miscellaneous elements
Previous topic: fn
Next topic: indextermref