A glossary is a feature that you can add to your output to help users understand the meaning of individual terms.
Use these steps to create a glossary and make it available to your end users:
- Add/Open Glossary You can add a new glossary file or open an existing one to work on it. See Adding a Glossary File or Opening a Glossary.
- Create Glossary Terms and Definitions After you add a new glossary or open an existing one, you can create glossary terms and definitions. See Creating Glossary Terms and Definitions.
- Create Glossary for Print Output To create a glossary manually for print output, you need to create a unique topic and insert a Glossary proxy into it. Alternatively, you can let Flare auto-generate one for you. See Creating a Glossary Manually for Print and Auto-generating Glossaries for Print.
- Insert Glossary Term Links If you have words and phrases in topics and snippets that are to be included in a glossary, you can turn them into links. See Inserting Glossary Term Links and Associating Glossaries with Targets.
- Edit Glossary You may need to edit the terms or definitions. You also may want to use styles to change look of glossary elements.
See Editing Glossaries and Using Styles to Change the Look of a Glossary.
- Enable Glossary After creating the glossary terms and definitions, you need to enable the glossary in the skin you want to use for the target. This step is necessary only for online output. See Enabling Glossaries in Skins.
- Associate Skin With Target Now that the glossary is enabled in the skin, you need to associate that skin with the target you are building. This step is necessary only for online output. See Associating Skins with Targets.
- Associate Master Glossary With Target Finally, you need to associate the glossary with a target. After you build the target, the glossary will be incorporated into the output
and terms will be converted to links in individual topics (if you have selected one of the term conversion options in the Target Editor). See Associating Glossaries with Targets.
In online output, users can view glossaries in a few ways, depending on the type of output you generate.
In most Tripane online outputs, users can click the term in the output glossary pane (or tab).
- In HTML5 Top Navigation and Side Navigation outputs, glossary terms and definitions are integrated into search results. See Glossary Integration with Search.
- If you use glossary term links, users can click the term in individual topics. You have the flexibility of converting only certain terms that you have marked, converting the first occurrence of terms in topics, or converting all occurrences. See Inserting Glossary Term Links.
The definition for a term can be simple text, which you supply at the same time that you create the glossary term. However, you can also create a topic specifically for a definition (with any formatting or elements that you might apply to a regular topic). The term can then be linked to that topic, instead of linking it to a simple text definition.
By default, Flare considers the case of text when automatically creating glossary term links
Also, a "Stem" option can be used for a glossary term.
This allows you to show only the basic (i.e., stem) format of a term in the glossary, rather than all variations (e.g., singular and plural). However, variations of the term will be included in any glossary term links that are created. (If you select this option, the check box to ignore the case of text is also selected automatically.)
When you use the stem or case fields in the Properties dialog, this is indicated by check boxes in the Glossary Editor.
Let's say you have the word "Target" in your glossary, with the "T" capitalized. Also, in your target you've opened the Glossary tab and told Flare to automatically convert all occurrences of matching terms to glossary links in your topics.
You might have topics that contain variations of the word, something like the following (with much more topic text than this, of course):
Suppose you generate your target without selecting either the "Ignore case…" or "Stem…" options.
In that case, the topic will look like this in the output, with only one term converted to a glossary term link—the word that matches the one in the glossary perfectly.
Now suppose you select the option to ignore the case of words.
In that case, the topic will look like this in the output, with two words converted to glossary term links.
And finally, suppose you select both options.
In that case, the topic will look like this in the output, with all of the words converted to glossary term links.
Note: The stem features supports the following languages:
You can apply conditions to terms in the Glossary Editor. See How to Apply Condition Tags to Glossary Terms.
If you want to apply the same condition(s) to multiple terms, hold down your SHIFT or CTRL key and select the terms. Then right-click and select Properties. Then on the Conditional Text tab, choose the condition(s).
A Condition column in the Glossary Editor indicates whether a term has conditions applied to it.
There are a couple of ways that you can take special advantage of search and glossaries when it comes to HTML5 output.
For HTML5 output, search results display glossary terms if they are used as the search text. In order to use this feature, you must be using MadCap Search. This feature is not supported for Google Search
Note: In order for a glossary term to display in the search results, the end user's search text must match the glossary term exactly, with no additional words (although it is not case-sensitive). For example, in the example above, only the word "table" was included in the search; therefore, the glossary term "Table" was displayed. But if we had searched for "table topic," no glossary term would have been displayed in the search results.
You can enable or disable this feature in the HTML5 Target Editor by selecting the Search tab, choosing MadCap Search, and clicking Include Glossary Results.
If you open an HTML5 Side Navigation, Top Navigation, Tripane, or Search Results skin, you will notice Search Glossary styles that let you control the look of this new feature (e.g., change the font color to make it stand out from the other search results). The Search Glossary Result style is used to control the entire area displaying the glossary search result. The Search Glossary Term and Search Glossary Definition styles are used to control the look of only the term and definition, respectively.
A search field is automatically added to the top of the Glossary pane in HTML5 output (Tripane only, not Side Navigation, Top Navigation, or skinless outputs). When you begin typing in the search field, Flare eliminates all other terms not matching what you type. So you end up with a much shorter group of matching terms. To return to the original full view of the glossary, just clear the search field.
Let's say you have a glossary that looks like this:
If you type the word "target," the view will change to this:
You can customize or hide this field. This includes the ability to change the following on the Styles tab of the Skin Editor.
- Font Settings
- Background Color
- Rounded Edges
By default, partial-word searching is enabled. This means that as a user types a search phrases, results are automatically displayed and the matching text is highlighted, even if the search text is only part of the glossary term. However, on the General tab of the Skin Editor, you can disable this feature. You might do this to improve performance. If you do this, results are no longer highlighted as users enter search text. See Enabling and Disabling Partial-Word Search for Glossaries.
You can use "Sort As" links for glossaries. This is similar to using "Sort As" index links (see Creating Index Links).
"Sort As" links can be useful for several reasons. You can use them if a keyword begins with a symbol (e.g., place <html> in the "h" section, instead of at the top) or if you want to sort acronyms based on their full spelling. You can also use "Sort As" links when working with multilingual documents, such as when you are using character sets that should be sorted phonetically.
When your glossary is displayed in the output (e.g., the Glossary window pane for Tripane output), by default terms are shown alphabetically. However, you can use the "Sort As" field in the Properties dialog to force a particular term to be displayed where you want it. This is especially useful if you are using "Sort As" links in your index, and you want words that appear in both places to be sorted in the same way.
Let's say you add the term "<html>" to your glossary. Because this word starts with a symbol, it would normally be sorted using the symbol. However, you want to sort it using the H. After you enter the term in your glossary, you add "html" as a "Sort As" term.
When you publish your output, the term is sorted correctly.
If you created a project with a previous version of Flare and then open a glossary in a recent version of Flare, you will be prompted to update the glossary and all content files containing related glossary term links.
This occurs because the markup for glossaries and glossary term links has changed due to new features in recent versions of Flare. This, however, is optional. Flare will continue to support the old markup if you do not update the files.
If you choose not to update a glossary (e.g., you might be connected to source control and don't want to update all of your files at the moment), you will continue to be prompted each time you open that glossary file.
Also, you will notice a button in the local toolbar of the Glossary Editor that is labeled "Update Glossary Reference Markup."
For most authors, you probably won't need to use this button. But if you import topics from an older Flare project, you might need to click this button to perform the glossary update for those files as well.