3.1.3.2.1 indexterm

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 the 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.

An indexterm that occurs in a topic prolog is interpreted as a point reference to the title of the topic. Likewise, 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 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 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 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 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 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 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 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 (see Figure 3-23 for samples):

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.

Contains

Doctype

Content model

topic (base), map (base), classifyMap, learningAssessment, learningBookmap, learningContent, learningMap, learningOverview, learningPlan, learningSummary

( text data or data or data-about or foreign or unknown or keyword or term or indexterm or index-base or index-see or index-see-also or index-sort-as) (any number)

topic (technical content), map (technical content), concept, ditabase, glossary, glossentry, glossgroup, reference, task, bookmap

( text data or data or data-about or foreign or unknown or keyword or apiname or option or parmname or cmdname or msgnum or varname or wintitle or term or abbreviated-form or indexterm or index-base or index-see or index-see-also or index-sort-as) (any number)

subjectScheme

( text data or data or data-about or foreign or unknown or keyword or term or indexterm or index-base) (any number)

machineryTask

( text data or data or data-about or foreign or unknown or keyword or wintitle or term or indexterm or index-base or index-see or index-see-also or index-sort-as) (any number)

Contained by

Doctype

Content model

topic (base)

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, index-see, index-see-also

map (base), classifyMap, learningMap

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, index-see, index-see-also

topic (technical content), concept

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, index-see, index-see-also, screen, codeblock, pd

map (technical content)

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, index-see, index-see-also, screen, codeblock, pd

ditabase

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, glossdef, glossUsage, glossScopeNote, index-see, index-see-also, screen, codeblock, pd

glossary, glossentry, glossgroup

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, glossdef, glossUsage, glossScopeNote, index-see, index-see-also, screen, codeblock, pd

reference

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, index-see, index-see-also, screen, codeblock, pd

task (strict), task (general)

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, index-see, index-see-also, screen, codeblock, pd

bookmap

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, index-see, index-see-also, organizationname, screen, codeblock, pd

subjectScheme

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords

machineryTask

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, reqcond, reqcontp, personnel, perscat, perskill, esttime, supequi, supply, spare, safecond, index-see, index-see-also, screen

learningAssessment, learningOverview, learningSummary

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, lcIntro, lcObjectivesStem, lcObjective, lcAudience, lcTime, lcPrereqs, lcSummary, lcNextSteps, lcReview, lcResources, lcChallenge, lcInstruction, index-see, index-see-also, lcQuestionBase, lcInstructornote, lcQuestion, lcOpenAnswer, lcFeedback, lcFeedbackCorrect, lcFeedbackIncorrect, lcAnswerContent, lcItem, lcMatchingItem

learningBookmap

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, index-see, index-see-also, organizationname

learningContent

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, lcIntro, lcObjectivesStem, lcObjective, lcAudience, lcTime, lcPrereqs, lcSummary, lcNextSteps, lcReview, lcResources, lcChallenge, lcInstruction, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, index-see, index-see-also, lcQuestionBase, lcInstructornote, lcQuestion, lcOpenAnswer, lcFeedback, lcFeedbackCorrect, lcFeedbackIncorrect, lcAnswerContent, lcItem, lcMatchingItem

learningPlan

p, note, lq, sli, li, itemgroup, dd, pre, lines, ph, stentry, indexterm, index-base, entry, keywords, abstract, bodydiv, section, sectiondiv, example, lcIntro, lcObjectivesStem, lcObjective, lcAudience, lcTime, lcPrereqs, lcSummary, lcNextSteps, lcReview, lcResources, lcChallenge, lcInstruction, lcGeneralDescription, lcGoals, lcNeeds, lcValues, lcOrgConstraints, lcEdLevel, lcAge, lcBackground, lcSkills, lcKnowledge, lcMotivation, lcSpecChars, lcWorkEnvDescription, lcPlanResources, lcProcesses, lcTaskItem, lcAttitude, lcPlanObjective, lcJtaItem, lcGapItemDelta, lcLearnStrat, lcAssessment, lcDelivery, index-see, index-see-also, lcQuestionBase, lcInstructornote, lcQuestion, lcOpenAnswer, lcFeedback, lcFeedbackCorrect, lcFeedbackIncorrect, lcAnswerContent, lcItem, lcMatchingItem

Inheritance

- topic/indexterm

Example

Figure 3-21 Single point 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:

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:

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:

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

Attributes

Name

Description

Data Type

Default Value

Required?

start

Specifies that an index entry is positioned at the beginning of a range. See the description of <indexterm> for more information.

CDATA

#IMPLIED

No

end

Specifies that an index entry is positioned at the end of a range; value matches the start attribute on another indexterm. See the description of <indexterm> for more information.

CDATA

#IMPLIED

No

keyref

Keyref provides a redirectable reference based on a key defined within a map. See 3.4.2.3 The keyref attribute for information on using this attribute.

CDATA

#IMPLIED

No

univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups)

A set of related attributes, described in 3.4.1.3 univ-atts attribute group

     

global-atts attribute group (xtrf, xtrc)

A set of related attributes, described in 3.4.1.2 global-atts attribute group

     

class

A common attribute described in 3.4.1.9 Other common DITA attributes

     

Previous Topic:  3.1.3.2 Indexing group elements

Next Topic:  3.1.3.2.2 indextermref

Parent Topic:  3.1.3.2 Indexing group elements

Sibling Topics:

3.1.3.2.2 indextermref

3.1.3.2.3 index-see

3.1.3.2.4 index-see-also

3.1.3.2.5 index-sort-as