---
title: "DITA: Acronyms and glossary terms"
description: "{% include notes.html %} With acroynyms, you can make words appear in their full form on the first instance of the page and subsequently in their abbreviated..."
canonical_url: https://idratherbewriting.com/acronyms_and_glossary/index.html
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

# DITA: Acronyms and glossary terms

> If you're creating a glossary and you want to link glossary terms to their definitions, you can use the `glossterm` type and key references to each glossary term within a topic. You can also use acronyms with your glossary terms.

With acroynyms, you can make words appear in their full form on the first instance of the page and subsequently in their abbreviated form (the acroynym). Each instance of the acronym (whether full or abbreviated) links to the glossary term.

> **Tip:** For a demo of glossary and acronym terms, as well as a glossary roll-up in the TOC, see this [Acronym and glossary demo](https://s3.us-west-1.wasabisys.com/idbwmedia.com/files/oxygendemos/glossary/).

## Create a glossary topic

First, create a new `glossterm` topic type. Only the `glossterm` and the `glossdef` are required elements in a glossary topic. However, if you want to have a full name and an acronym for the glossary term, you must add some more elements after the `glossdef`. Add a `glossBody` tag and define the `glossSurfaceForm` and the `glossAcronym` as shown in the following example:

```xml
<glossentry id="opentoolkit">
    <glossterm>Open Toolkit</glossterm>
    <glossdef><p>The open toolkit is what processes your DITA files to transform them into webhelp,
                 pdf, and other outputs.</p>
              <p>There are other processors besides the OT that can achieve similar results.</p>
              <p>OxygenXML does use the Open Toolkit to do its processing, but Trisoft uses another processor.</p>
</glossdef>
<!-- the rest of this content is optional-->
    <glossBody>
        <glossSurfaceForm>Open Toolkit (OT)</glossSurfaceForm>
        <glossAlt>
            <glossAcronym>OT</glossAcronym>
        </glossAlt>
    </glossBody>
</glossentry>
```

The `glossSurfaceForm` is the form of the term the first time it "surfaces" on the page. The `glossAcronym` is the form that appears on subsequent references. Both forms link back to the glossary definition.

## Reference your glossary term on your map

To include the glossary term in your output, in your map file, add this:

```xml
<glossref keys="opentoolkit" href="ot.dita" />
```

In DITA, a resource must be referenced on your DITA map to be included in the output. Here we're using the key `opentoolkit` to refer to this glossary term reference. The nice thing about keys is that you can change what the key refers to without breaking all your links (keys function like variables). The key `opentoolkit` will look at the content in the ot.dita file and pull in the glossary term name automatically to render as the name of the link.

For example, suppose I've been referring to the key `opentoolkit` through my documentation. The glossary term name is "Open Toolkit." Then I decide that I really want to refer to it as "DITA Open Toolkit." I won't need to change any of my documentation references, because they're all using `opentoolkit` to refer to the glossary term. I just change the glossary term title that the `opentoolkit` key points to (or the `glossSurfaceForm` or `glossAcronym`). Then all the references will be updated.

## Reference the glossary term in a topic

You can refer to the glossary term a couple of different ways in topics: `abbreviated-form` or `term`.

Here's an example using the `abbreviated-form` element:

```xml
The <abbreviated-form keyref="opentoolkit"/> is what processes your DITA files.
Make sure you have the latest version of the <abbreviated-form keyref="opentoolkit"/>.
```

The output will look like this:

```xml
The <strong class="ph b">Open Toolkit (OT)</strong> is what processes your DITA files. Make sure
      you have the latest version of the <strong class="ph b">OT</strong>.
```

> **Note:** For this demo, rather than hyperlinks to the glossary or acronym term, I've just formatted the words in bold. In the Oxygen webhelp file, they would be links to the topics. See the [source code topic in the demo.](https://s3.us-west-1.wasabisys.com/idbwmedia.com/files/oxygendemos/glossary/#glossary_demo_source.html)

Notice how the `abbreviated-form` element intelligently displayed the `glossSurfaceForm` on the first reference, and the `glossAcronymForm` on subsequent references? If you have acronyms and you want this functionality, make sure to use the `abbreviated-form` when referring to the glossary term.

If the glossary term doesn't have an acronym form, you could also just reference it using `term`, like this:

```xml
The <term keyref="opentoolkit"/> is what processes your DITA files.
Make sure you have the latest version of the <term keyref="opentoolkit"/>.
```

The output will look like this:

```xml
The <strong class="ph b">OT</strong> is what processes your DITA files. Make sure
      you have the latest version of the <strong class="ph b">OT</strong>.
```

In both instances of the word, the `glossAcronymForm` is used. If the glossary file didn't have a `glossAcronymForm`, the `title` would be used instead.

(By the way, you don't have to use either abbreviated-form or term to refer to a glossary term. You could also just refer to it with an `xref`. However, if you just use `xref`, no tooltip appears when you mouse over the link. Hence this method isn't recommended.)

## A note about style

Note that the content in `glossBody` will appear in the webhelp output unless you add some styling that hides it. Create the following CSS styles and add it to your [DITA: Webhelp skins](https://idratherbewriting.com/webhelp_skins) CSS to hide this content:

```xml
.glossSurfaceForm, .glossAlt {
    display: none;
}
```

## Organizing glossary files

Where should glossary terms be organized -- in your root folder with other topics, or in a subfolder? Personally, I like to keep my glossary files organized in a subdirectory called "glossary." However, you can organize them however you want.

## Displaying your glossary in the TOC

As with other resources, you have to include your glossary files on your DITA map if you want them to appear in your output. (If you have a lot of glossary terms, you can put them in a separate DITA map and then reference that DITA map on your root DITA map using `mapref`. ) Your glossary terms are just links to your glossary files. Here's how I do it.

It can look odd to dedicate an entire page to a term that if the term is only a couple of sentences long, so I consolidate all of my glossary terms so they appear in the same TOC entry. For a demo, look at the [Demo Glossary Overview](https://idratherbewriting.com/glossary_overview#topic_kjk_1kn_hq) in the TOC.

To consolidate glossary terms on a single page in the output, use the `chunk="to-content"` attribute in your glossary overview topic, like this:

```xml
<topicref href="glossary_overview.dita" chunk="to-content">
   <topicref href="glossary/ot.dita" toc="yes"/>
   <topicref href="glossary/conref.dita" toc="yes"/>
</topicref>
```

> **Note:**See the [demo](https://s3.us-west-1.wasabisys.com/idbwmedia.com/files/oxygendemos/glossary/index.html) for an example of the glossary integrated into the TOC.

This `chunk="to-content"` attribute will merge the children into itself.

You might think that you can just use `glossref` elements with chunk="to-content", like this:

```xml
<topicref href="glossary_overview.dita" chunk="to-content">
   <glossref href="glossary/ot.dita" keys="opentoolkit" toc="yes"/>
   <glossref href="glossary/conref.dita" keys="conref" toc="yes"/>
</topicref>
```

However, if you use this method, the key references will no longer work. The `chunk` attribute screws them up. In places where the glossary term should appear, you'll just see blank spaces. As a workaround, when using the `chunk` attribute, you must separate out the `topicref` from the `keyref` elements, like this:

```xml
<topicref href="glossary_overview.dita" chunk="to-content">
  <topicref href="glossary/ot.dita" toc="yes"/>
  <topicref href="glossary/conref.dita" toc="yes"/>
</topicref>

<!-- glossary keys -->
<glossref keys="opentoolkit" href="ot.dita"/>
<glossref keys="conref" href="conref.dita"/>
```

(I'm not sure if this is a bug in Oxygen or the OT or what. At any rate, that's is how you do it.)

## Reusing glossary definitions

A common scenario with re-use is to re-use definitions of your glossary terms in other parts of your documentation. For example, suppose you want to reuse the Open Toolkit definition in the glossary term topic above. Suppose you have a topic listing a table with field definitions:

```xml
            <topic id="topic_table">
              <title>Sample table of definitions</title>
              <body>
                <table>
                  <tgroup cols="2">
                    <thead>
                      <row>
                        <entry>Fields</entry>
                        <entry>Definitions</entry>
                      </row>
                    </thead>
                    <tbody>
                      <row>
                        <entry><abbreviated-form
                keyref="opentoolkit"/></entry>
                        <entry><strong class="ph b">[glossary
                definition]</strong></entry>
                      </row>
                    </tbody>
                  </tgroup>
                </table>
                <p>Besure to check out <topicsetref id="hey"/></p>
              </body>
            </topic>
```

You can't use `conref` to re-use the `glossdef` element into the table's `entry` element because the `entry` element doesn't allow `glossdef` elements.

The way to do this is by wrapping the `glossdef` content inside a `ph` element (phrase element), and then embed the `ph` element into the table row. Here I wrap the `glossdef` content inside a `ph` element:

```xml
<glossdef><ph id="ot_def">The open toolkit is what processes your DITA files to transform them into
webhelp, pdf, and other outputs.</ph></glossdef>
```

Then you use `conref` to insert the `ph` element into your table element, like this:

```xml
<entry><ph conref="filename.dita#opentoolkit/ot_def"/>
```

Here's a sample result pulling the glossary definitions into another topic: [Sample table of definitions](https://idratherbewriting.com/sample_table_def).

The table code simply looks like this:

```xml
   <table>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Fields</entry>
          <entry>Definitions</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry><term keyref="conref"/></entry>
            <entry><p conref="glossary/conref.dita#conref"/>
            </entry>
          </row>
          <row>
            <entry><term keyref="opentoolkit"/></entry>
            <entry><ph conref="filename.dita#opentoolkit/ot_def"/>
          </row>
        </tbody>
      </tgroup>
    </table>
```

This technique works well for short glossary definitions, but what if you have a definition that spans several paragraphs? Do you have to create three separate conref elements?

To include multiple sibling elements (such as three paragraph tags in a row), you can use what's called a "conref range." First you add an ID tag to the first and last element that you want to bring over. If my glossary definition has three paragraphs, I could tag it like this:

```xml
<glossdef>
  <p id="ot_first">The open toolkit is what processes your DITA files to transform them
    into webhelp, pdf, and other outputs.</p>
  <p>There are other processors besides the OT that can achieve similar results.</p>
  <p id="ot_last">OxygenXML does use the Open Toolkit to do its processing, but
      Trisoft uses another processor.</p>
    </glossdef>
```

Notice how I added an ID attribute to the first and last paragraph tags.

Now I use a `conref` range to bring over the first and last element and everything in between:

```xml
<p conref="glossary/ot.dita#opentoolkit/ot_first"
conrefend="glossary/ot.dita#opentoolkit/ot_last"/>
```

Note that although you can use this technique to bring over longer amounts of content, generally you want to keep your glossary definitions to a paragraph level size. If you use multiple paragraphs, the paragraphs will make the tooltip for the glossary link big and ugly.

Also note that if you reuse a glossary definition in another topic, your topic now requires the glossary definition to be present in the output for the topic to be valid. If you have scenarios where you don't want your outputs to include the glossary definition, then don't set up this dependency. Instead, pull the conref from another file that serves as a general "warehouse" of re-usable components.