A Glossary in UPK effectively associates Web Pages to key terms. UPK will then turn any instance of that key term within a Topic (or other content object) to which that Glossary is assigned into a hyperlink to the associated Web Page. You could do this manually by creating Web Pages (as explained above) and then creating hyperlinks to these manually, but the advantage of using the Glossary functionality is that UPK will ‘automatically’ find each occurrence of the glossary term and create the hyperlink. I say ‘automatically’ in quotation marks, as UPK does not do this completely automatically. You have to tell it to go and create the hyperlinks, but once you tell it to do so, it will dutifully go off and find ‘every’ occurrence of all of the terms in the glossary and create the hyperlinks to the definition.

And I say ‘every’ in quotation marks, because UPK won’t necessarily link every instance of the term. UPK allows you to choose (at the Library level) whether it turns literally every occurrence of the term found in a location into a hyperlink, or only the first occurrence. A location here is effectively a single Bubble or Web Page. One could well ask why UPK doesn’t provide the option to create a Glossary link only for the first occurrence of the term in a Topic. The simple answer is that it does not necessarily know which occurrence is the first, because the Topic could include Alternative Paths. So UPK takes an over-cautious approach, and considers each block of information separately.

This option is specified in the Options panel (menu option Tools|Options), under the Content Defaults|Glossary section, as shown in the following screenshot:

Creating a glossary

To create a Glossary in UPK, follow these steps:

1. From the main Library screen, click on the folder within which you want to create the Glossary. You can create the Glossary in any folder, but it makes sense to have a single folder that contains the Glossary file itself, and all of the Web Pages used for the terms.
2. Select menu option File|New|Glossary.

The Glossary Editor is opened in a new tab within the UPK Developer window, as shown in the following screenshot:

To create glossary entries from within the Glossary, follow these steps:

1. Enter the glossary term in the first free Glossary Term field.
2. Click in the Definition Link field on the same line. An ellipsis (…) is displayed on the rightmost side of the field.
3. Click on the ellipsis. The Edit Definition Link dialog box is displayed.
4. Click on the Create New Web Page field.
5. The Save As dialog box is displayed.
6. Navigate to the directory in which you want to save the Glossary definition. Again, it makes sense to save these in the same folder as the Glossary itself.
7. The Name field will default to the glossary term specified in the Glossary Term field. It is recommended that you keep this default, and use the definition term as the Web Page name. You could use any other name, if you wanted to (UPK does not use this name to locate the definition; it uses its own, internal identifier) but using the same name will allow you to easily locate the term Web Page if you need to.
8. Click on the Save button. A new tab is opened for the Web Page.
9. Enter the Glossary description into this page.
10. The Web Page will use the default font and colors. You can override these defaults, if required.
11. Close the Web Page by clicking on the x on the rightmost side of the open tab list. You are passed back to the Glossary Editor.
12. Enter a suitable ToolTip text for the glossary entry in the Tooltip field. This text will be displayed when the user hovers the mouse over the hyperlinked glossary term.
13. If only whole instances of the glossary term should be turned into hyperlinks (for example, if the term is Order then “Orders” and “Ordering” will not be hyperlinked), then select the Match Whole Word option. Otherwise, make sure that this option is not selected.
14. If only text that matches the case of the term should be turned into hyperlinks (for example, if the term is Order then “order” will not be hyperlinked), then select the Match Case field. Otherwise, make sure that this option is not selected.
15. Repeat Steps 1 to 14 for all additional terms that you want to add to the Glossary.

To create a glossary entry that uses an existing Web Page for the glossary term, follow these steps:

1. Enter the glossary term in the first free Glossary Term field.
2. Click in the Definition Link field on the same line. An ellipsis (…) is displayed on the rightmost side of the field.
3. Click on the ellipsis. The Edit Definition Link dialog box is displayed.
4. Click on the Create Link button. The Insert Hyperlink dialog box is displayed.
5. Navigate to, and select, the Web Page that contains the glossary description.
6. Click on OK. The Edit Definition Link dialog box is redisplayed.

   You can edit the Web Page directly from this dialog box, by clicking on the Edit Web Page icon.

7. Click on OK. You are returned to the Glossary tabbed page.

Once you have defined all required Glossary entries, save and close the Glossary, by following the steps shown below:

1. Click the Save button to save your changes to the Glossary. The Save As dialog box is displayed.
2. Navigate to the directory in which you want to save the Glossary.
3. Enter a suitable name for the Glossary in the Name field.
4. Close the Glossary Editor by clicking on the x on the rightmost side of the open tab list.

An example of a partially-populated Glossary is shown in the next screenshot:

You can see from the Definition Link column above that all of the Glossary definition files are stored in the same, single folder, called Glossary. This is the same folder that the Glossary object itself is stored in. Personally, I find it useful to keep all of the content objects for the Glossary in the same single folder. This is not strictly necessary, but it does keep things organized.

You will also note that the Tooltip is the same in every case. I tend to always use the tooltip Glossary so that the user knows that the hyperlink links to the Glossary, and not to another form of Web Page.

Assigning a Glossary to content objects

Creating a Glossary is only half the story. You need to manually assign the Glossary to each object that you want to use that Glossary (that is, for which you want the terms specified in the Glossary to be hyperlinked to the Glossary definitions).

Version Difference

In OnDemand Version 8.7 and earlier, a single Glossary was created for a Title, and was automatically applied to all content objects within that Title. In UPK 3.5, it is possible to have multiple Glossaries within a single Library, so it is necessary to specify which content objects should use which Glossary.

This assignment is done via the content object’s Properties, as shown in the screenshot below.

The Glossary property is available for Modules, Sections, Topics, and Web Pages. This means that you could potentially assign one Glossary to a Module, another Glossary to a Section within this Module, and a third Glossary to a Topic within that Section. Not that you’re very likely to want to do this. But you could.

The further implication of the requirement to assign a Glossary to each content object individually is that you can define multiple Glossaries, and assign different Glossaries to different objects. I’d question the wisdom of assigning one glossary to a Module, and then an entirely different Glossary to a Topic within that Module, but I can certainly see the benefit of having multiple Glossaries available in a Library that contained (for example) simulations for multiple applications; you could create application-specific Glossaries (as you no doubt do at the moment) and then assign each Glossary to only the content objects for the relevant application.

The downside (for those of us who favor modularization and reuse) is that it is only possible to assign a single Glossary to any given object. So it is not possible to, say, create a company-wide Glossary and separate application-specific Glossaries, and then assign the company-wide Glossary and the relevant application-specific glossary to a single Topic. But more resourceful readers will have already worked out how to get around this limitation. Need a clue? Glossary entries are just Web Pages, and any given Web Page can be reused in multiple places. Need more help? A Web Page can be included in more than one Glossary. So you should first define Web Pages for all of your Glossary terms. You can then create multiple Glossaries (for example, one for each application), and include whichever terms’ Web Pages you need to in each of the glossaries. If a term applies to two applications, then simply include the Web Page for that term in the Glossaries for both applications. Simple! Of course there is some slight duplication of effort as you need to create the entry in the actual Glossary content object twice (once in each glossary), but you are reusing the individual definitions, so it could be worse.

Unfortunately, unlike Templates, it is not possible to specify a default Glossary in your user defaults. This means that this assignment must be done separately for each content object. However, there are a couple of shortcuts that UPK provides which avoid the need to assign the Glossary to content objects one by one. First, if you select multiple content objects (Modules, Sections, Topics, or Web Pages) and display the Properties pane, then you can assign the Glossary to all of the selected objects in one fell swoop. Second, if you assign a Glossary to a Module, then any new Sections or Titles that you create within that Module – that is, from within the Outline Editor – will inherit this Glossary assignment. However, it is important to note that this will only apply to new content objects. If you assign a Glossary to an outline element and then insert pre-existing content objects into this outline element, then these pre-existing content objects will not inherit the Glossary assignment.

Regenerating the Glossary links

Glossary links are not created (or updated) automatically. You need to tell UPK to go and search through your content objects and turn any instances of the Glossary terms into links to the Glossary definitions. This is good in that you can at least have control over when it does this, but bad in that it is easy to forget to do so.