While it is not necessary to understand the 'technical' side of a Glossary document in order to use one, 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, who intend to create a new Glossary from scratch or from an existing folder of files, or who are just curious as to how we got this stuff to work.

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

   Glossaries are intended to mimic the 'other' book (a folder of clauses) by housing multiple document assembly terms within its 4 corners. The individual elements of a folder are denoted by 'files' contained within that folder.

   Likewise, a Glossary needs to be a way to define the scope of each term. This is done using 'bookmarks.'

•A bookmark is simply a standard Word feature that allows the user to reference to a specific location or to a selection of text within a source document.

•A bookmark can be a single 'spot' in the document or a sizable 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.

•And as used by Pathagoras, retrieval of text, and its insertion into the target document, during a document assembly session is accomplished without even opening the source document. Bookmarks allow smooth and 'silent' transfer of text from source to target.

  Creating a Bookmark (the 'basics')

It is easy to add bookmarks to any Word document manually. Pathagoras tools can create bookmarks for you automatically, but you do not need Pathagoras for this purpose. You can do it yourself. 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).

  Bookmark Naming Rules:

Whether you are adding new terms to an existing or to a new Glossary, or want to change the name of an existing Glossary term, there are two bookmark naming rules that must be observed:

1.The name must start with a letter of the alphabet 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 or punctuation marks, are allowed.

  A 'Pathagoras Glossary':

As indicated above, a Pathagoras Glossary is a simple Word document containing terms that you wish to use for document assembly purposes, each term of which is bounded by bookmarks to indicate its scope. To enhance the document assembly aspects of the system, however, Pathagoras pre-pends two 'identifiers' immediately 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.
Here is an idea for you to consider when you want to make choices and groupings a bit more 'visible' to the end user. If a clause is a sub-division of a parent or when you want to group clauses for display, add two (or more) spaces to the subject line. This indenting will show when you select 'Display by Subject.'

  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 within the opening and closing bookends. See section below on "Showing the 'bookends' of a bookmarked term.:

  Showing the boundaries of a bookmarked term: The range of a bookmarked term is noted by two light-gray-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 gray 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 the Utilities/Settings screen. Look for and click the button (toward the bottom-right) that says [Show Bookmarks] or [Hide Bookmarks].  When clicked, the button will toggle to the opposite value.

  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!

  Debugging a Glossary:

   Because a Glossary is a plain text document, it is easy to 'debug'. However, Pathagoras does not expect that of you, and provides tools to automate this process. If you have issues with a Glossary that you cannot explain, you should run a 'Structure & Integrity Check' against the Glossary. Here are the steps:

1.Display the Glossary onto a Word editing screen.

2.With the Glossary 'on display,' click the Pathagoras Features dropdown list and select "Glossary Tools".

3.Click "Other Glossary Tools".

4.Click the <Structure & Integrity> button.

Line endings for Glossary terms:

   Unlike 'documents' which force you to have a final 'Enter' (pilcrow character (¶)) at the end of all text, you are not so constrained with glossaries. You can control whether the Glossary term contains a final Enter. But failure to exercise this control can lead to some unexpected results, especially when it comes to formatting issues. Read on for the 'why.'

   Word, and therefore Pathagoras, embeds all formatting code for a particular paragraph of text into the 'pilcrow' (The 'pilcrow' is the 'backwards P' shaped character: ¶) character at the end of that paragraph. (The ‘pilcrow’ is the ‘backwards P’ shaped character: ¶ that closes every paragraph in a document. You can see it by clicking that same character at the top of a document (Home tab)

•If the bookmarks include that final pilcrow, then the text will come in fully formatted.

•If the bookmarks exclude that final pilcrow, the text comes in as unformatted text. The text will take on the style/characteristics of the receiving paragraph.

   You can manually change the 'scope' of the bookmarks. To do so, display the Glossary. Make sure 'Show Bookmarks' is set to 'on.' (See text above for instructions on how to display bookmarks.)  Study the document, looking especially for whether the final pilcrow is within or without the closing bookmark. To enclose the pilcrow within the closing bookmark when it is not initially, place your cursor just inside the bookmark and press the 'enter button. Sometimes it is necessary to type a 'real' character (a period will work) and an enter. Then delete the extra character. By playing with the sequence you can accomplish what you want.

   You can also use Pathagoras editing tools to accomplish the above. First, click your cursor to somewhere inside the term you want to change. Then, from the Pathagoras Features dropdown list, click Glossary Tools. Next, select Glossary Toolbar (floating). This is what you should see:

 

 

From the toolbar that will appear, select 'Change scope'.

Then, choose the action you desire from the next screen that appears: