1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>glossary.collection</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="../index.html" title="DocBook XSL Stylesheets: ReferenceDocumentation"><link rel="up" href="glossary.html" title="Glossary"><link rel="prev" href="firstterm.only.link.html" title="firstterm.only.link"><link rel="next" href="glossary.sort.html" title="glossary.sort"><link rel="copyright" href="copyright.html" title="License"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">glossary.collection</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="firstterm.only.link.html">Prev</a></td><th width="60%" align="center">Glossary</th><td width="20%" align="right"><a accesskey="n" href="glossary.sort.html">Next</a></td></tr></table><hr></div><div class="refentry" title="glossary.collection"><a name="glossary.collection"></a><div class="titlepage"></div>
<div class="refnamediv"><h2><span class="refentrytitle">glossary.collection</span></h2><p>
glossary.collection
— Name of the glossary collection file
</p></div>
<div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2>
<a name="glossary.collection.frag"></a><pre class="programlisting">
<xsl:param name="glossary.collection"></xsl:param>
</pre>
</div>
<div class="refsection" title="Description"><a name="id1392319"></a><h2>Description</h2>
<p>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
<span class="quote">“<span class="quote">extract</span>”</span> the ones you need in each document.</p>
<p>That's the purpose of the
<a href="../html/glossary.collection.html"><em class="parameter"><code>glossary.collection</code></em></a> parameter. To setup a global
glossary <span class="quote">“<span class="quote">database</span>”</span>, follow these steps:</p>
<div class="refsection" title="Setting Up the Glossary Database"><a name="id1392360"></a><h3>Setting Up the Glossary Database</h3>
<p>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.</p>
<p>Here's an example glossary:</p>
<div class="informalexample">
<pre class="programlisting">
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossary
PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<glossary>
<glossaryinfo>
<editor><firstname>Eric</firstname><surname>Raymond</surname></editor>
<title>Jargon File 4.2.3 (abridged)</title>
<releaseinfo>Just some test data</releaseinfo>
</glossaryinfo>
<glossdiv><title>0</title>
<glossentry>
<glossterm>0</glossterm>
<glossdef>
<para>Numeric zero, as opposed to the letter `O' (the 15th letter of
the English alphabet). In their unmodified forms they look a lot
alike, and various kluges invented to make them visually distinct have
compounded the confusion. If your zero is center-dotted and letter-O
is not, or if letter-O looks almost rectangular but zero looks more
like an American football stood on end (or the reverse), you're
probably looking at a modern character display (though the dotted zero
seems to have originated as an option on IBM 3270 controllers). If
your zero is slashed but letter-O is not, you're probably looking at
an old-style ASCII graphic set descended from the default typewheel on
the venerable ASR-33 Teletype (Scandinavians, for whom /O is a letter,
curse this arrangement). (Interestingly, the slashed zero long
predates computers; Florian Cajori's monumental "A History of
Mathematical Notations" notes that it was used in the twelfth and
thirteenth centuries.) If letter-O has a slash across it and the zero
does not, your display is tuned for a very old convention used at IBM
and a few other early mainframe makers (Scandinavians curse <emphasis>this</emphasis>
arrangement even more, because it means two of their letters collide).
Some Burroughs/Unisys equipment displays a zero with a <emphasis>reversed</emphasis>
slash. Old CDC computers rendered letter O as an unbroken oval and 0
as an oval broken at upper right and lower left. And yet another
convention common on early line printers left zero unornamented but
added a tail or hook to the letter-O so that it resembled an inverted
Q or cursive capital letter-O (this was endorsed by a draft ANSI
standard for how to draw ASCII characters, but the final standard
changed the distinguisher to a tick-mark in the upper-left corner).
Are we sufficiently confused yet?</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>1TBS</glossterm>
<glossdef>
<para role="accidence">
<phrase role="pronounce"></phrase>
<phrase role="partsofspeach">n</phrase>
</para>
<para>The "One True Brace Style"</para>
<glossseealso>indent style</glossseealso>
</glossdef>
</glossentry>
<!-- ... -->
</glossdiv>
<!-- ... -->
</glossary></pre>
</div>
</div>
<div class="refsection" title="Marking Up Glossary Terms"><a name="id1392391"></a><h3>Marking Up Glossary Terms</h3>
<p>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
<span class="quote">“<span class="quote">placeholder</span>”</span> glossary entries would be very tedious. So instead,
support for <a href="../html/glossary.collection.html"><em class="parameter"><code>glossary.collection</code></em></a> relies on implicit linking.</p>
<p>In your source document, simply use <a href="http://docbook.org/tdg5/en/html/firstterm.html"><code class="sgmltag-element">firstterm</code></a> and
<a href="http://docbook.org/tdg5/en/html/glossterm.html"><code class="sgmltag-element">glossterm</code></a> to identify the terms you wish to have included
in the glossary. The stylesheets assume that you will either set the
<code class="sgmltag-attribute">baseform</code> attribute correctly, or that the
content of the element exactly matches a term in your glossary.</p>
<p>If you're using a <a href="../html/glossary.collection.html"><em class="parameter"><code>glossary.collection</code></em></a>, don't
make explicit links on the terms in your document.</p>
<p>So, in your document, you might write things like this:</p>
<div class="informalexample">
<pre class="programlisting"><para>This is dummy text, without any real meaning.
The point is simply to reference glossary terms like <glossterm>0</glossterm>
and the <firstterm baseform="1TBS">One True Brace Style (1TBS)</firstterm>.
The <glossterm>1TBS</glossterm>, as you can probably imagine, is a nearly
religious issue.</para></pre>
</div>
<p>If you set the <a href="../html/firstterm.only.link.html"><em class="parameter"><code>firstterm.only.link</code></em></a> parameter,
only the terms marked with <a href="http://docbook.org/tdg5/en/html/firstterm.html"><code class="sgmltag-element">firstterm</code></a> will be links.
Otherwise, all the terms will be linked.</p>
</div>
<div class="refsection" title="Marking Up the Glossary"><a name="id1392474"></a><h3>Marking Up the Glossary</h3>
<p>The glossary itself has to be identified for the stylesheets. For lack
of a better choice, the <code class="sgmltag-attribute">role</code> is used.
To identify the glossary as the target for automatic processing, set
the role to <span class="quote">“<span class="quote"><code class="literal">auto</code></span>”</span>. The title of this
glossary (and any other information from the <code class="sgmltag-element">glossaryinfo</code>
that's rendered by your stylesheet) will be displayed, but the entries will
come from the database.
</p>
<p>Unfortunately, the glossary can't be empty, so you must put in
at least one <a href="http://docbook.org/tdg5/en/html/glossentry.html"><code class="sgmltag-element">glossentry</code></a>. The content of this entry
is irrelevant, it will not be rendered:</p>
<div class="informalexample">
<pre class="programlisting"><glossary role="auto">
<glossentry>
<glossterm>Irrelevant</glossterm>
<glossdef>
<para>If you can see this, the document was processed incorrectly. Use
the <parameter>glossary.collection</parameter> parameter.</para>
</glossdef>
</glossentry>
</glossary></pre>
</div>
<p>What about glossary divisions? If your glossary database has glossary
divisions <span class="emphasis"><em>and</em></span> your automatic glossary contains at least
one <a href="http://docbook.org/tdg5/en/html/glossdiv.html"><code class="sgmltag-element">glossdiv</code></a>, the automic glossary will have divisions.
If the <a href="http://docbook.org/tdg5/en/html/glossdiv.html"><code class="sgmltag-element">glossdiv</code></a> is missing from either location, no divisions
will be rendered.</p>
<p>Glossary entries (and divisions, if appropriate) in the glossary will
occur in precisely the order they occur in your database.</p>
</div>
<div class="refsection" title="Formatting the Document"><a name="id1392553"></a><h3>Formatting the Document</h3>
<p>Finally, when you are ready to format your document, simply set the
<a href="../html/glossary.collection.html"><em class="parameter"><code>glossary.collection</code></em></a> parameter (in either a
customization layer or directly through your processor's interface) to
point to your global glossary.</p>
<p>The stylesheets will format the glossary in your document as if
all of the entries implicilty referenced appeared there literally.</p>
</div>
<div class="refsection" title="Limitations"><a name="id1392581"></a><h3>Limitations</h3>
<p>Glossary cross-references <span class="emphasis"><em>within the glossary</em></span> are
not supported. For example, this <span class="emphasis"><em>will not</em></span> work:</p>
<div class="informalexample">
<pre class="programlisting"><glossentry>
<glossterm>gloss-1</glossterm>
<glossdef><para>A description that references <glossterm>gloss-2</glossterm>.</para>
<glossseealso>gloss-2</glossseealso>
</glossdef>
</glossentry></pre>
</div>
<p>If you put glossary cross-references in your glossary that way,
you'll get the cryptic error: <code class="computeroutput">Warning:
glossary.collection specified, but there are 0 automatic
glossaries</code>.</p>
<p>Instead, you must do two things:</p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>Markup your glossary using <a href="http://docbook.org/tdg5/en/html/glossseealso.html"><code class="sgmltag-element">glossseealso</code></a>:</p>
<div class="informalexample">
<pre class="programlisting"><glossentry>
<glossterm>gloss-1</glossterm>
<glossdef><para>A description that references <glossterm>gloss-2</glossterm>.</para>
<glossseealso>gloss-2</glossseealso>
</glossdef>
</glossentry></pre>
</div>
</li><li class="listitem">
<p>Make sure there is at least one <a href="http://docbook.org/tdg5/en/html/glossterm.html"><code class="sgmltag-element">glossterm</code></a> reference to
<em class="glossterm">gloss-2</em> <span class="emphasis"><em>in your document</em></span>. The
easiest way to do that is probably within a <a href="http://docbook.org/tdg5/en/html/remark.html"><code class="sgmltag-element">remark</code></a> in your
automatic glossary:</p>
<div class="informalexample">
<pre class="programlisting"><glossary role="auto">
<remark>Make sure there's a reference to <glossterm>gloss-2</glossterm>.</remark>
<glossentry>
<glossterm>Irrelevant</glossterm>
<glossdef>
<para>If you can see this, the document was processed incorrectly. Use
the <parameter>glossary.collection</parameter> parameter.</para>
</glossdef>
</glossentry>
</glossary></pre>
</div>
</li></ol></div>
</div>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="firstterm.only.link.html">Prev</a></td><td width="20%" align="center"><a accesskey="u" href="glossary.html">Up</a></td><td width="40%" align="right"><a accesskey="n" href="glossary.sort.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">firstterm.only.link</td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top">glossary.sort</td></tr></table></div></body></html>
|
