Sample Glossary Application
This document explains how to use the glossary database within the context of a Docbook XML-based publishing system. The document assumes some knowledge of Docbook XML on a Linux system where the prerequisite development setup of the project has been satisfied.
Introduction
For the purpose of demonstration we have created a document called sample.xml. It resides in the trunk/dict/common/ directory. This document is in Docbook XML 'article' format. It is really a non-sense document that has no meaning other than to illustrate the semantic markup of glossary entries and serves as data input to our XML publishing toolchain.
For convenience we have provided sample Docbook XSL customization layers in trunk/dict/libs/. In this case, we will be using the
trunk/dict/libs/single-html-cust.xsl file.
For additional convenience we have created a
When running our sample application the product will be a single HTML document based on the data contents and structure of sample.xml. The document will be formatted in accordance with the settings specified in single-html-cust.xsl. During processing, glossary terms defined in sample.xml will be collected from our glossary database and added to a "Glossary" located at the end of the document. Our glossary database current contains 21297 terms. We do not have that many terms defined in sample.xml. Only those terms and their definitions defined in sample.xml will be included in the "Glossary".
Our sample application therefore illustrates how, using Docbook XML, authors can maintain a single, reusable glossary database so that a "Glossary," containing only terms relevant to a given document, may be automatically generated.
Application Components
Our XML-based application is comprised of the following components:
-
sample.xml - a Docbook Article defining glossary entries that exist in the glossary database.
-
single-html-cust.xsl - a Docbook XSL customization layer that imports the standard Docbook XSL Stylesheets and includes two additional Docbook XSL customization layers that define parameters and template customizations. These are used to configure how our XML-based application will perform processing and how the target presentational document, in this case a single HTML document, will look.
-
sample: - a
make target, specific in trunk/Makefile that will execute the command used to invoke the XSLT processor, pass the sample.xml and single-html-cust.xsl files to the XSLT processor input and define that the transformed result be output to a file called sample.html in a directory called trunk/build/terms/. The make target will automatically create this directory for you.
The transformed result of the sample application can be viewed here.
Collection Methods
The collection methods described below are based on the recommendation from Bob Staytons most excellent book, "Docbook XSL - The Complete Guide." We highly recommend this book to anyone working with Docbook.
Preparing a Glossary Section
In order to enable glossary collection a glossary section must be created at the end of the Docbook XML document in which a "Glossary" is required. In addition the glossary element must have a role attribute with a value auto and must contain at least one glossentry. The content of the glossentry is not important. It will be replaced during processing with glossary terms and definitions contained in the glossary database. Here is an example. The same code can be found at the end of sample.xml.
<glossary role="auto">
<glossentry>
<glossterm>Dummy</glossterm>
<glossdef>
<para>Now you see me, next you won't.</para>
</glossdef>
</glossentry>
</glossary>
Specifying the Glossary Database Location
Our single-html-cust.xsl customization layer is comprised of three lines.
<xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/current/html/docbook.xsl"/>
<xsl:include href="html-common-cust.xsl"/>
<xsl:include href="common-cust.xsl"/>
The first line is a xsl:import command that imports the standard HTML Docbook Stylesheets into our custom layer.
The second line is a xsl:include command that includes customizations for HTML into the custom layer.
The third line is another xsl:include command that includes customizations that are actually common to both HTML and PDF transformation scenarios used in our system. It includes a file called common-cust.xsl. On closer examination of this files contents you will find a section call "Glossaries."
<!-- Glossaries -->
<xsl:param name="glossterm.auto.link" select="1"/>
<xsl:param name="firstterm.only.link" select="1"/>
<xsl:param name="glossary.collection">../glossary/glossary.xml</xsl:param>
<xsl:param name="glossentry.show.acronym" select="'primary'"/>
In this section is a number of xsl:param commands. The parameter glossary.collection is used to specify the location of the glossary database. When this parameter is set to a value the Docbook Stylesheets will, for each glossentry found in an XML input, attempt to locate a term amongst the glossary entries found in the glossary database specified. When a matching term is found it is automatically added to the glossary section defined at the end of the Docbook XML document being processed.
by Sean Wheller