Glossary database

Glossary database
	Chapter 17. Glossaries

If you find yourself needing the same glossary entries in more than one document, you can maintain a separate glossary entry database. Keeping the entries in one place ensures consistency between publications and makes it easier to maintain. It gets better. Your glossary can be assembled automatically from the glossterm and firstterm elements scattered throughout your document. And they can be automatically hot linked to the generated glossary.

A glossary database is simply a separate DocBook document with root element glossary that contains a collection of glossentry elements. Each entry in the database document must have a unique glossterm element, because that is used for matching. Put your entries in the order you want them to appear in any of your glossaries. You can use glossdiv elements too.

To generate a glossary automatically, you do three things:

Create a placeholder glossary element in your document, with a role="auto" attribute. In DocBook 4's DTD, glossary cannot be empty, so you must put one dummy glossentry in it. It does not matter what it says, because it will not be used. In DocBook 5, the dummy entry is not needed because it permits an empty glossary.
Add glossterm and firstterm elements anywhere in your document as needed. Either the text content or the element's baseform attribute value must match the glossterm in one of the entries in your database.
Process your document with the stylesheet parameter glossary.collection set to the filename of your database document.

When the stylesheet reaches your nearly empty <glossary role="auto"> element in your document, it opens the glossary database document specified by the glossary.collection parameter. For each glossentry in the database, it looks at the text content of its glossterm child. It then checks to see if there is a glossterm or firstterm element somewhere in your document that matches it (or one with a baseform attribute that matches). If so, then it outputs that glossentry in your glossary.

You have a couple of options:

You can restrict the glossary to generating entries only for firstterm elements in your document by setting the firstterm.only.link parameter to 1.
You want to turn on the automatic hot links from each glossterm in your text to the matching glossentry in the glossary, then set the glossterm.auto.link parameter to 1.

Glossary database catalog entry

If you need to share a glossary database among several books, you might consider using an XML catalog entry to locate the database file. Once you set it up, all of your documents will be able to use the same collection, and you can move the collection when you need to, and then you just need to change the single catalog entry. See Chapter 5, XML catalogs for general information on catalogs.

First set the glossary.collection parameter to any generic path:

<xsl:param name="glossary.collection">file:///foo/gloss.xml</xsl:param>

Then add an entry to your XML catalog that maps the generic path to the real path:

 <uri
    name="file:///foo/gloss.xml"
    uri="file:///c:/usr/share/xml/glossary-database.xml"/>

When you process your stylesheet with a catalog-aware processor (and tell it where to find the catalog), then the generic path will be mapped to the specific path.

Links in a glossary collection

There are significant limitations on cross references within a glossary collection. These arise because the glossary collection is processed as a separate document in its own context, not in the context of the main document.

A glossary entry cannot cross reference back to the body of the document. It often useful to refer from a glossary entry to a section of the document that provides more information, but that is not possible when you use a glossary collection.
A cross reference from one glossentry to another in the collection using either glossterm, glosssee, or glossseealso may fail. However, there is a workaround that will enable them to work. See the glossary.collection parameter reference page in the stylesheet documentation.
Even if your links within your glossary collection do not give an error, they can still fail in the output. That can happen when the target entry is not included in the glossary generated for that document. If there is no glossterm in the document body that references the target entry, then it will not be included in the generated glossary. The stylesheet thinks the entry is present in the context of the glossary collection during processing, so there is no error message. But the generated link will fail when viewed.

You can still link from your document body to entries in the glossary collection.