##### 14.7.3.1 Specifying first-use rules for glossary-term abbreviations

DITA2Go determines whether to output the full form or the abbreviated form, based in part on where the reference occurs:

DITAmaps (including bookmaps) and their submaps

Topic title elements .

DITAmaps (including bookmaps) and their submaps

In maps and submaps, at the first occurrence of:

    <abbreviated-form keyref="key"/>

where key is the value defined on the keys attribute of the <glossref> element that references the <glossentry> topic for the term, DITA2Go includes the content of the <glossSurfaceForm> element for the term. For all subsequent occurrences in the same topic, DITA2Go includes the abbreviated form instead: that is, the content of the <glossAcronym> element for the term.

DITA2Go provides a way for you to specify the map level where the first-use rule should apply. For example, to show the full term the first time it is used in a <chapter>:

    [Glossary]
    ; ResetAbbrevAt = Level in bookmap to restart (put out
    ; glossSurfaceForm again).  One of: Document, Part, Chapter,
    ; Head1, ..., Head6, or Topic; default is Topic.
    ResetAbbrevAt = Chapter

The default value of ResetAbbrevAt is Topic.

DITA2Go treats appendix as equivalent to Chapter. Part and Chapter apply only to bookmaps. In a bookmap, the Head1 through Head6 levels start under Chapter.

Head1 through Head6 apply to the titles of topics, not to section titles within topics.

The first occurrence of <abbreviated-form> at the level specified by ResetAbbrevAt gets the full term. All subsequent occurrences at the same level, and at lower levels in the same map and its submaps, get the abbreviated form.

Topic title elements

To specify whether terms in titles should be treated differently from terms in text with respect to the first-use rule:

    [Glossary]
    ; UseAbbrevInTitles = Yes (default, use glossAcronym,
    ; not glossSurfaceForm, in title elements) or No
    ; (treat title instances the same as any others).
    UseAbbrevInTitles=Yes

When UseAbbrevInTitles=Yes, every instance of <abbreviated-form> in a topic <title> gets the content of <glossAcronym>. However, if it is the instance that would be considered first use according to the value of ResetAbbrevAt, the next occurrence in that topic of <abbreviated-form> with the same key gets the content of <glossSurfaceForm>.

When UseAbbrevInTitles=No, title elements are treated the same as any other elements with respect to first use of <abbreviated-form>.

Previous Topic: 14.7.3 Configuring use of abbreviations for glossary terms

Next Topic: 14.7.3.2 Overriding first-use rules for abbreviations

Parent Topic: 14.7.3 Configuring use of abbreviations for glossary terms

Sibling Topics:

14.7.3.2 Overriding first-use rules for abbreviations

14.7.3.3 Specifying @class for the abbreviated-form element

14.7.3.4 Formatting output for the abbreviated-form element