Creating a Glossary of Terms

A Glossary of Terms is defined in a ditamap using either standard topicref elements to glossary entry topics, or using glossref elements (introduced in DITA 1.2).

A Glossary of Terms is made up of multiple small glossentry topics, each with a structure of a term (glossterm) element followed by a definition (glossdef) element. The glossary of terms is assembled by referencing all the glossentry topics in a ditamap.

In DITA 1.2, instead of using the standard topicref element to reference the glossentry topics, you can use the glossref element. The glossref element is specialised from the topicref element, but differs in having a mandatory keys attribute.

The keys attribute is used for the automatic generation of links from terms in topic text to the corresponding glossary definition. The links are indirect links, in that the term in the topic links to a key, and the target of that key is defined in the ditamap. (This method of linking is known as indirection.)

The following code sample compares a topicref and a glossref:
<topicref href="mechanical/g_abs_brake_system.dita" />

<glossref  href="mechanical/g_brake_system.dita" keys="abs" />

To specify that a link to be generated from a term to the glossary definition during publishing, you must use a term element, or specialised form of the term element named abbreviated-form. Both term and abbreviated-form elements have a keyref attribute, which is the reference to the corresponding key in the ditamap glossref element. (The keyref attribute was introduced in DITA 1.2.)

For example, to specify a link from the acronym ABS to a glossary definition of "ABS Brake System", the following code could be used:
<p>Your car has <abbreviated-form keyref="abs"/>.

Except for small documents, using a separate ditamap for the glossary of terms, and then embedding the glossary ditamap in the main ditamap for the collection, is the architecture most easy to manage.