(y)our wiki about all things technical communication

User Tools

Site Tools


Glossaries through tooltips

Glossaries versus tooltips

If your documentation contains a lot of technical terms or acronyms, you can support your reader with a glossary.
Glossaries are usually limited to static lists, added as a chapter at the end of a manual.
However, Oxygen’s online help outputs offer a solution whereby users are no longer forced to leave the page they are reading: glossaries through tooltips. Tooltips are one-term glossary pop-ups that appear on screen if you hover your mouse over the term or acronym. If you click the term, the glossary item opens as a separate topic.



  1. Create a glossterm topic.
  2. Add the glossary term to the glossary map.
  3. Reference the glossary term in a topic.

Create a glossterm topic

  1. Select File > New.
  2. In the “New” window, select Framework templates > DITA > topic > Learning > Glossentry [DITA / topic]
  3. Click Create.
  4. Fill out the glossterm and the glossdef items.
  5. Save the glossentry in your project.
    You can give this topic any name you like, but for clarity’s sake, we suggest you start its name with glos_.

Add the glossary term to the glossary map

Your publication needs to contain a glossary map.
If this is not the case yet, add a ditamap to your publication.
You can give this map any name you like, but for clarity’s sake, we suggest you call it !Glossary.

  1. Open the glossary map in the DITA Maps Manager.
  2. Right-click the glossary map and select Append child > Glossary Reference….
  3. Select your newly created glossentry.
  4. Click Insert and close.
    OXygen adds the topic to the map as a glossref but gives an error message that the glossref needs a key.
  5. Open the publication or the glossary map in the author window.
  6. Select the newly added glossref.
  7. Fill out its keys attribute in the Attributes window.
    You can give this keys attribute any name you like, but for clarity’s sake, we suggest you give it the same name as its glossterm or title.
  8. Save your changes.

Reference the glossary term in a topic

  1. In a topic, select the words for which you wish to show a tooltip.
  2. Surround them with a term element.
  3. In the Attributes window, open the keyref attribute list by clicking the downward arrow in the keyref field.
    It lists all possible glossentries for your publication.
  4. Select the appropriate keyref.
  5. Save your changes.
oxygen/glossaries_through_tooltips.txt · Last modified: 2017/04/13 14:23 by freya