Search results

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.

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

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>.

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:

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:

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 CSS to hide this content:
.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 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:

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

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

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

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

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

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

Here's a sample result pulling the glossary definitions into another topic: Sample table of definitions.

The table code simply looks like this:

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

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

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.