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
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.
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.
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
child. It then checks to see if there is a
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
You have a couple of options:
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.
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:
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.
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
glossseealso may fail. However, there is a workaround that will enable them to work. See the
glossary.collection parameter reference page in the stylesheet
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.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises