The 'Technical Side' to Glossaries

 Top  Previous  Next

   While it is not necessary to understand the 'technical' side to glossary documents in order to use them, a bit of a discussion on the care and feeding of glossaries may nevertheless be in order. This section is intended for those who regularly use glossaries, or who are just curious as to how we got all of this stuff to work.

   Glossaries are standard Word documents. That is an important concept to remember. Treat them as such (which means that they really are not something special, just a little different.)

  Because glossaries are intended to mimic the 'other' book (a folder of clauses) by housing multiple document assembly terms, there needs to be a way to separate one term from the other, and to define the scope of each term. This is done using a standard Word 'bookmark.' A bookmark is simply a named reference to a specific location or to a selection of text within a document. A bookmark can be a single 'spot' in the document or a sizeable block of text ( a word, a paragraph or many pages -- size doesn't matter). Instead of scrolling through the document to locate the text, the text can be quickly accessed by reference to the bookmark.

   It is easy to add bookmarks to any Word document manually. You do not need Pathagoras to do it. Here are the steps:

1.Highlight the text that you want to bookmark.
2.Click the Insert button in the Word menu.
3.Click Bookmark.
4.At the screen that appears, type the name you want to assign to the highlighted text. (See Name Rules below).

  When Pathagoras adds a new bookmark to a glossary, it performs the same steps that are listed above. To enhance the document assembly aspects of the system, however, Pathagoras pre-pends two 'identifiers' above each bookmarked term. This is so you can readily discern the name and subject of the term.

•The first identifier, two lines above the bookmarked text, and in red, is a repeat of the bookmark name. (You could discover the name of the bookmark by clicking within the bookmark itself, pressing Insert|Bookmark. The text in the Name field is the name of the bookmark.) We put the bookmark name on the 'face' of the document to make it easier for you to see the name. Please note: the red line is simply text.  It is not linked to the bookmark. It is just sitting there. Changing the red line alone will not change the name of the bookmark. Note also that the color red is for emphasis only. The color is not substantively important. (We will cover 'changing the name of a glossary term' in a separate section.)
•The second identifier is the blue line. This line will always appear immediately above the bookmarked text. The blue line reflects the subject that you assigned to the clause (or if you didn't assign a subject, the one that Pathagoras assigned as a default). Unlike the red line, the blue line is somewhat substantive. A change on the blue line will be picked up into your next display of the Clause Selection Screen or in a DropDown List upon creation or a refresh. Change blue lines with impunity until you have your subjects just the way you want them.

  Bookmark Naming Rules: If you directly add terms to a glossary, or change the name of any existing glossary term, there are two bookmark naming rules that must be observed:

1.The name must start with a letter or an underscore character. (If you use the underscore character as the first character in a bookmark name, it will make the bookmark 'hidden.' )
2.The remaining characters of the name must be letters or numbers or the underscore character. No other symbols, including spaces, are allowed.

  Changing a glossary term name: As noted above, you cannot change the name of a glossary term simply by changing the red line. But you can successfully change the glossary name by following these steps:

1.Place the cursor anywhere within the bookmark area.
2.Click Insert|Bookmark. The name of the bookmark within which the cursor sits will appear at the top.
3.Click the "Go To" button at the bottom of the bookmark screen. This will highlight the entire scope of the bookmark.
4.Click the "Delete" button just to the left of <Go To> (don't worry, only the bookmarks are deleted, not the text).
5.At the top of the screen type the new name. Press <Add> to save the new term.
6.Manually type within the red line to reflect the new name. If you wish to modify the subject, make the changes in the blue line.

  Changing the scope of a glossary term: If you found a bit of text 'outside' the closing bookmark, don't worry. It is easy to get it inside the closing bookmark. Here are two ways. (1) Cut/copy the 'outside text' (to put it into the clipboard), move the cursor to inside the closing bookmark and paste it in. (2) The second method is to highlight the entire block of text that you want the bookmark to encompass, and click Insert|Bookmark. The name of the first bookmark that the block you highlighted surrounds will appear at the top of the screen. Most likely this is the name you want. Click <Add> and the bookmark will be expanded to include the entire block of text

  Adding or deleting new text in a glossary term: Editing text within a bookmark should not worry you  at all. A bookmarked section of a document is still just standard text within a standard Word document. Delete, add, copy, cut, paste, text, pictures, tables, number fields. Whatever you want is fully possible. The bookmark ends adjust to your new text without you having to do anything. Just make sure, if you are adding text to the beginning or the end of the term that you are actually within the opening and closing bookends. See section below on "Showing the 'bookends' of a bookmarked term.:

  Showing the 'book-ends' of a bookmarked term: The range of a particular bookmarked term is noted by two light-grey-in-color brackets at the beginning and end of the term. More often than not, they will not be visible without take a few more steps because Word does not display bookmarks by default. Even when 'exposed' the light grey color can be hard to see, so look carefully.

  Word provides you one method, and Pathagoras has 2, for you to 'show' the bookends:

•In Word, click Tools|Options|View and check the Bookmarks item.
•In Pathagoras, display either the Main Menu or the Utilities/Settings screen. Look for and click the button that says [Show Bookmarks] (the buttons are in grey and are at the bottom).  When clicked, the button will toggle to Hide Bookmarks.

 

  How glossaries work: Even with all of the above in mind, it is not necessarily clear how text gets moved from a glossary to a new document. Nor is it obvious as to how the names of the glossary terms get displayed into the Clause Selection Screen or DropDown Lists. This section discusses what is happening behind the scenes:

Each time you call on a glossary, Pathagoras opens that glossary to gather information from it.

Taking advantage of the "bookmarks" table that Word automatically creates when a document is saved with bookmarks inside, Pathagoras jumps in a very rapid fashion to each bookmark in the glossary. It captures the name (but not content) of the bookmark and then, for each, jumps back one line to capture the subject line (the blue line).

Pathagoras then closes the glossary and, with the information in memory, creates the Clause Selection Screen or DropDown List.

When you call for a term in the glossary, Pathagoras quickly opens the document, goes to and copies the text of the specific bookmark, pastes it into the document under assembly. That search, copy, paste  process is repeated until all requested terms are inserted.

That is all there is to it!