DITA: Acronyms and glossary terms
glosstermtype 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
glosstermtopic type. Only the
glossdefare 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
glossBodytag and define the
glossAcronymas shown in the following example:
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
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
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
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:
The output will look like this:
Notice how the
abbreviated-form element intelligently displayed
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
term, like this:
The output will look like this:
In both instances of the word, the
glossAcronymForm is used. If the
glossary file didn't have a
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
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
glossBodywill 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:
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
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,
chunk="to-content" attribute will merge the children into
glossrefelements with chunk="to-content", like this:
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:
(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:
conref to re-use the
into the table's
entry element because the
element doesn't allow
The way to do this
is by wrapping the
glossdef content inside a
element (phrase element), and then embed the
ph element into the
table row. Here I wrap the
glossdef content inside a
conref to insert the
ph element into your
table element, like this:
Here's a sample result pulling the glossary definitions into another topic: Sample table of definitions.
The table code simply looks like this:
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:
Notice how I added an ID attribute to the first and last paragraph tags.
conrefrange to bring over the first and last element and everything in between:
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
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.