Creating Glossary Terms and Definitions

After you add a new glossary or open an existing one, you can create terms and definitions.

How to Create Glossary Terms and Definitions

  1. If you do not have one already, add a glossary file.
  2. From the Project Organizer, open the glossary to which you want to add glossary entries.
  3. In the local toolbar of the Glossary Editor, click to add a new item. A new row is added to the glossary, with "MyTerm" shown as the default name. In addition, the Properties dialog for the glossary term opens.

  4. In the Terms section of the dialog, replace the text "MyTerm," and type the new term.

    If you want to insert a variable in a field, you can click Add a variable definition.. The variable will appear as syntax in the field, but in the output the variable definition will be shown.

    Note If you want to see the variable syntax replaced by the variable definition, click Toggles between showing variable definition and syntax in the local toolbar of the editor. This shows you the "Evaluated Term," which determines the actual text of the variable.

  5. (Optional) If you want to sort a glossary entry using a different term, in the Sort As field, enter the term you want to use for sorting. "Sort As" terms appear in the Sort As column of the glossary.

    Tip Use a "Sort As" term if you want to sort a glossary term as something else. This can be useful when a term begins with a symbol (e.g., place <html> in the "h" section, instead of at the top of the glossary), or if you are using character sets that need to be sorted phonetically.

  6. (Optional) If you want the glossary term to include variants (e.g., plurals, other tenses), select Stem words to include term variants in automatic link creation. This is useful because you do not have to create multiple glossary terms if you frequently use different forms of a term.
  7. (Optional) If you want the glossary term to include both upper- and lowercase variants, select Ignore case in automatic link creation. This is automatically checked if you stem the glossary term.
  8. In the Definition section, select either Text (if you want to provide a simple text definition for the term) or Topic (if you have created a topic for the definition and want the term to link to it). For print-based output, it probably makes the most sense to use the "Text" option.

  9. If you selected "Text," type a definition in the space next to that option. If you selected "Topic," click The browse ellipsis button opens to more options., then find and select a topic.

  10. (Optional) If you want to update glossary term links, click Update matching glossary term links and save glossary. This will find glossary term links in your content files where the text exactly matches what is in the old version of the glossary (before you made changes). It will update those glossary term links with your changes from the new version of the glossary and save that glossary file. If you do not select this option, the glossary term links will not be updated in the content files.

    Example You have a glossary term link for the term "screenshot." In a topic it might look like this:

    The link points to the "screenshot" term in your glossary file.

    Suppose you want to change the term from "screenshot" to "snapshot."

    Option Enabled

    In your glossary, you double-click the screenshot term. The Properties dialog opens. You change the term to snapshot. And at the bottom of the dialog, you make sure that Update matching glossary term links and save glossary has a check mark.

    A message lets you know that the files with related glossary term links have been updated.

    Your glossary now looks like this:

    And a topic containing the glossary term link looks like this:

    In the output it might look like this:

    Option Disabled

    Using this same scenario, you might disable the option if you are fine with existing topics keeping the term "screenshot," while changing the term in the glossary to "snapshot."

    So after you change the term from "screenshot" to "snapshot" in your glossary, you disable the Update matching glossary term links and save glossary check box.

    Your glossary looks like this:

    But a topic containing the glossary term link looks like this (with "screenshot" instead of "snapshot"):

    And the output looks like this:

    Warning Use caution with this option, because if you alternate checking it and unchecking it, you can get into a state where the glossary term link text in the content files does not match the old glossary text in the glossary file, so it will not be updated anymore.

  11. (Optional) If you plan to use glossary term links, click the Style tab. Then select one of the following styles:
    • Expanding Displays the definition in expanding text when the link is clicked.
    • Popup Displays the definition (or linked topic) in a popup when the user hovers the cursor over the link.
    • Hyperlink Opens the linked topic (if you selected one) in its own window, as opposed to a popup. If the definition is provided as simple text rather than a linked topic, this option opens that glossary term link as a popup.

    Note By default, glossary terms will not be converted to links if they are found in h1 through h6 styles, as well as hyperlinks (i.e., content with the <a> tag). However, if the same term is found in, say, a regular paragraph, the term will be converted to a link. If you want to avoid certain terms being converted to links automatically (or if you want to reverse this setting for h1-h6 and hyperlink styles), you can use an option to ignore glossary terms. See Ignoring Glossary Terms in Styles.

  12. (Optional) If you want to apply conditions to the term, select the Conditional Text tab and choose the relevant conditions.
  13. Click OK.
  14. Click Save the active file. to save your work.

Duplicate Glossary Terms

Duplicate terms in a glossary file are identified by red icons. Green icons represent glossary terms that are unique. Also, the number of duplicates in the glossary file is shown in the local toolbar.

This feature is not case-sensitive. For example, if you have "Condition tag" and "condition tag" as terms, they are considered duplicates.

What’s Next?

After you create glossary terms and definitions, you need to enable glossaries in the skin you want to use for the target. See Enabling Glossaries in Skins.

If you are creating print-based output and want the entire glossary to be included in the manual (in addition to any glossary term links that are converted to footnotes), you also need to create a topic and insert a Glossary proxy into it. In the output, the proxy is replaced by the generated glossary. See Creating a Glossary Manually Using a Proxy.