DITA: Acronyms and glossary terms

Create a glossary topic

<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

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

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

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

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

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

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.