Edit online

Working with a Glossary of Terms in DITA

There are several ways to manage a Glossary of Terms in DITA, but it is considered best practices to create a separate submap for the glossary and embed that glossary map in the main (root) map. The actual glossary terms are small glossary entry topics that are referenced in the glossary map. You can add links to the glossary terms in the output and you can even define abbreviated forms for terms that have an acronym or some other type of abbreviation.

How to Create a Glossary of Terms in Oxygen XML Author Eclipse plugin

Even though there are several ways to create a glossary and reference the glossary terms, the following is the recommended approach:
  1. Create a new submap for your glossary and embed it in your main map.
  2. Create a glossary entry topic (<glossentry>) for each glossary term. The <glossentry> element may contain numerous optional glossentry elements, but every glossentry topic must contain a <glossterm> and <glossdef> element. The <glossterm> is the name of the term while the <glossdef> is its definition.

    Here is an simple example:
    <glossentry id="ddl">
        <glossterm>Data Definition Language</glossterm>
        <glossdef>A language used for defining database schemas.</glossdef>
    </glossentry>
    The easiest way to create a glossentry topic in Oxygen XML Author Eclipse plugin:
    1. Click the New file wizard button on the toolbar.
    2. Type glossentry in the search field at the top of the dialog box.
    3. Select the Glossentry DITA topic type, configure the name and optionally the title, and click Create.
  3. Reference each glossary entry topic in your glossary submap using the <glossref> element. This element requires a @keys attribute. Please make sure the @print attribute is set to yes to show the glossary also in the PDF output.
    <glossref keys="gloss_ddl" href="ddl.dita" print="yes"/>
    The easiest way to reference a glossentry in Oxygen XML Author Eclipse plugin:
    1. With the glossary entry topic opened in the main editor, open the glossary submap in the DITA Maps Manager, right-click the map node and select Append Child > Reference to the currently edited file (if you already have existing glossentry topics, you can right-click the glossentry where you want to insert the new one and select Insert After > Reference to the currently edited file).

      Step Result: This opens the Insert Reference dialog box.

    2. Go to the Keys tab and enter a name in the Define keys field.
    3. Go to the Attributes tab and select Glossary Reference from the Reference type drop-down list at the top of the dialog box.
    4. Click Insert and Close.
Tip: You could also group multiple glossentry topics into a single collection by using the <glossgroup> element.

Using Abbreviated Forms (Acronyms) with Glossary Terms

The <abbreviated-form> element can be used for glossary terms that you want to appear in an abbreviated form (such as an acronym). Abbreviated forms are expanded to their full form the first time that they appear in a document, and then all subsequent instances will display the short form (or acronym). You would need to define the long and short forms in the <glossentry> and then reference it with the <abbreviated-form> element (instead of the <term> element).

The recommended best practices for defining the long and short forms would be to use a structure similar to this:
<glossentry id="ddl">
  <glossterm>Data Definition Language</glossterm>
  <glossBody>
    <glossSurfaceForm>Data Definition Language (DDL)</glossSurfaceForm>
    <glossAlt>
      <glossAcronym>DDL</glossAcronym>
    </glossAlt>
  </glossBody>
</glossentry>

The long form is declared using the <glossSurfaceForm> element while the short form is declared using the <glossAcronym> element.

Then you need to reference the glossentry that contains the long and short forms using the <abbreviated-form> element:
<abbreviated-form keyref="gloss_ddl"/>

For more information about the recommended best practices for using abbreviations, including information about using multiple languages, see: http://www.oasis-open.org/committees/download.php/29734/AcronymBestPractice_08112008.doc.