Description
Glossaries maintained independently across a set of documents
are likely to become inconsistent unless considerable effort is
expended to keep them in sync. It makes much more sense, usually, to
store all of the glossary entries in a single place and simply
“extract” the ones you need in each document.
That's the purpose of the
glossary.collection parameter. To setup a global
glossary “database”, follow these steps:
Setting Up the Glossary Database
First, create a stand-alone glossary document that contains all of
the entries that you wish to reference. Make sure that each glossary
entry has an ID.
Here's an example glossary:
Marking Up Glossary Terms
That takes care of the glossary database, now you have to get the entries
into your document. Unlike bibliography entries, which can be empty, creating
“placeholder” glossary entries would be very tedious. So instead,
support for glossary.collection relies on implicit linking.
In your source document, simply use firstterm and
glossterm to identify the terms you wish to have included
in the glossary. The stylesheets assume that you will either set the
baseform attribute correctly, or that the
content of the element exactly matches a term in your glossary.
If you're using a glossary.collection, don't
make explicit links on the terms in your document.
So, in your document, you might write things like this:
If you set the firstterm.only.link parameter,
only the terms marked with firstterm will be links.
Otherwise, all the terms will be linked.
Marking Up the Glossary
The glossary itself has to be identified for the stylesheets. For lack
of a better choice, the role is used.
To identify the glossary as the target for automatic processing, set
the role to “auto”. The title of this
glossary (and any other information from the glossaryinfo
that's rendered by your stylesheet) will be displayed, but the entries will
come from the database.
Unfortunately, the glossary can't be empty, so you must put in
at least one glossentry. The content of this entry
is irrelevant, it will not be rendered:
What about glossary divisions? If your glossary database has glossary
divisions and your automatic glossary contains at least
one glossdiv, the automic glossary will have divisions.
If the glossdiv is missing from either location, no divisions
will be rendered.
Glossary entries (and divisions, if appropriate) in the glossary will
occur in precisely the order they occur in your database.
Formatting the Document
Finally, when you are ready to format your document, simply set the
glossary.collection parameter (in either a
customization layer or directly through your processor's interface) to
point to your global glossary.
A relative path in the parameter is interpreted in one
of two ways:
If the parameter glossterm.auto.link
is set to zero, then the path is relative to the file containing
the empty glossary element in the document.
If the parameter glossterm.auto.link
is set to non-zero, then the path is relative to the file containing
the first inline glossterm or
firstterm in the document to be linked.
Once the collection file is opened by the first instance described
above, it stays open for the current document
and the relative path is not reinterpreted again.
The stylesheets will format the glossary in your document as if
all of the entries implicilty referenced appeared there literally.
Limitations
Glossary cross-references within the glossary are
not supported. For example, this will not work:
If you put glossary cross-references in your glossary that way,
you'll get the cryptic error: Warning:
glossary.collection specified, but there are 0 automatic
glossaries.
Instead, you must do two things:
Markup your glossary using glossseealso:
Make sure there is at least one glossterm reference to
gloss-2 in your document. The
easiest way to do that is probably within a remark in your
automatic glossary: