Working with a Glossary of Terms in DITA

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 Editor:

   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 Editor:

   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.

To specify that a link is generated in the output from the glossary term to its definition, use the <term> element (or <abbreviated-form> element as described in the next section) with a @keyref attribute that references the corresponding key specified in the <glossref>. Of course, the <glossref> points to the <glossentry> topic where the glossary term is defined.

<term keyref="gloss_ddl"/>

The easiest way to add a <term> element and reference the glossary term in Oxygen XML Editor:

1. Place the cursor at the location where you want to insert a link to the glossary term.
2. In the DITA Reusable Componts view, go to the Keys tab and use the search filter field at the top of the view to find the key for the particular glossary term.
3. Right-click the key and select Insert as Keyref > More > Term.

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>

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

<abbreviated-form keyref="gloss_ddl"/>