Creating Glossaries

Glossaries enable you to define and easily implement a set of terms to use in your documentation.

Glossary Term

You use the term element to link to the glossary entry topic. If you hover over the term, a tooltip with the term definition appears.

Figure 1. Glossary Term.

The following example shows the glossary term “publish” in the HTML5 output.

Glossary Entry Topic

If you click the term element that links to the glossary entry topic, you open the glossary entry topic.

Figure 2. Glossary Entry Topic

Create a Glossary

Using glossary terms in your topics requires initial configuration.

  1. Create glossary terms. See Create Glossary Entry Topics.
  2. Create a map and add the glossary entry topics to the map. See Create a Glossary Map.
    Tip: We recommend having a global, reusable glossary map that contains all your glossary entry topics, or having glossary maps for major product lines. This makes using the glossary terms in your publications easier because they're all bundled together in a glossary map that can be easily added to publications where the glossary terms are used.
  3. Add the glossary map to the shared map. See Add a Glossary Map to the Shared Map.
    Tip: We recommend having your glossary map in a shared map to help safeguard against unresolved links during publish.
  4. Add the shared map to the deliverable map. See Add the Shared Map to a Deliverable Map.
Insert glossary terms into topics. See Insert a Glossary Term to a Topic.

Create Glossary Entry Topics

Use the glossary entry topic to define individual glossary terms and their definitions.

  1. In the content library, navigate to a folder and click Create New.
  2. Select Glossary Entry.
  3. Fill in the Title field.
    The title of the glossary entry topic is used as the glossary term.
  4. Click Create & Edit.
  5. Define the glossary term and its terminology information by doing the following:
    1. In the Definition field, enter a definition for the term.
    2. Optional: Enter additional information about the glossary term such as an abbreviation, acronyms, synonyms, etc.
  6. If needed, repeat the procedure for each glossary term.

Create a Glossary Map

Create a map that contains a collection of glossary terms.

Create glossary terms. See Create Glossary Entry Topics.
  1. In the content library, navigate to a folder and click Create New.
  2. Select Default Map.
  3. Fill in the Title field.
    Enter Glossary Map
  4. Click Create & Edit.
  5. Add the glossary entry topics to the glossary map by doing the following:
    1. From the content library, drag and drop the glossary entry topic into the map.
    2. If needed. from the context menu, select glossref and click Insert.
    3. If you don't see a dialog, in the left pane, click the Key icon.
    4. In the dialog, enter a key name that is unique and easy to identify with the glossary term. Click Update.
      Enter: glossDITA
    5. If needed, repeat 5 for each glossary glossary entry topic.

Add a Glossary Map to the Shared Map

Add your glossary map to a shared warehouse map for easy reuse.

Tip: We recommend having your glossary map in a shared map to help safeguard against unresolved links during publish.
  1. In the content library, hover over the shared map and click the Dock button.
  2. In the content library right-click the shared map and select Dock.
  3. In the content library, navigate to the glossary map you want to add to the shared map.
  4. Drag and drop the glossary map into the Map Editor and click Insert if needed.

Add the Shared Map to a Deliverable Map

Ensure that the shared map is added to a deliverable map.

  1. In the content library, hover over the deliverable map and click the Dock button.
  2. In the content library, right-click the deliverable map and select Dock.
  3. In the content library, navigate to the shared map you want to add to the deliverable map.
  4. Drag and drop the shared map into the deliverable map and click Insert if needed.
  5. Hover-over the shared map and click the wrench icon.
  6. From the processing-role drop-down menu, select resource-only.

Insert a Glossary Term to a Topic

You add a glossary term to a topic by key-referencing glossary entry topics.

Create a glossary of terms. See Create a Glossary.
  1. In the content library, hover over a topic and click Open.
  2. In the content library, double-click a topic.
  3. Place your cursor where you want to insert a glossary term.
  4. Press Shift > Cmd > K (Mac) or Shift > Ctrl > K (Windows).
  5. In the dialog, do the following:
    1. Optional: Start typing the glossary key name.
      Typing the glossary key name makes the keys list shorter.
    2. In the keys list, double-click the relevant glossary key name.