1 <refentry xmlns="http://docbook.org/ns/docbook"
\r
2 xmlns:xlink="http://www.w3.org/1999/xlink"
\r
3 xmlns:xi="http://www.w3.org/2001/XInclude"
\r
4 xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
\r
5 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
\r
6 version="5.0" xml:id="glossary.collection">
\r
8 <refentrytitle>glossary.collection</refentrytitle>
\r
9 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
\r
12 <refname>glossary.collection</refname>
\r
13 <refpurpose>Name of the glossary collection file</refpurpose>
\r
17 <src:fragment xml:id="glossary.collection.frag">
\r
18 <xsl:param name="glossary.collection"></xsl:param>
\r
22 <refsection><info><title>Description</title></info>
\r
24 <para>Glossaries maintained independently across a set of documents
\r
25 are likely to become inconsistent unless considerable effort is
\r
26 expended to keep them in sync. It makes much more sense, usually, to
\r
27 store all of the glossary entries in a single place and simply
\r
28 <quote>extract</quote> the ones you need in each document.</para>
\r
30 <para>That's the purpose of the
\r
31 <parameter>glossary.collection</parameter> parameter. To setup a global
\r
32 glossary <quote>database</quote>, follow these steps:</para>
\r
34 <refsection><info><title>Setting Up the Glossary Database</title></info>
\r
36 <para>First, create a stand-alone glossary document that contains all of
\r
37 the entries that you wish to reference. Make sure that each glossary
\r
38 entry has an ID.</para>
\r
40 <para>Here's an example glossary:</para>
\r
44 <?xml version="1.0" encoding="utf-8"?>
\r
45 <!DOCTYPE glossary
\r
46 PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
\r
47 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
\r
49 <glossaryinfo>
\r
50 <editor><firstname>Eric</firstname><surname>Raymond</surname></editor>
\r
51 <title>Jargon File 4.2.3 (abridged)</title>
\r
52 <releaseinfo>Just some test data</releaseinfo>
\r
53 </glossaryinfo>
\r
55 <glossdiv><title>0</title>
\r
58 <glossterm>0</glossterm>
\r
60 <para>Numeric zero, as opposed to the letter `O' (the 15th letter of
\r
61 the English alphabet). In their unmodified forms they look a lot
\r
62 alike, and various kluges invented to make them visually distinct have
\r
63 compounded the confusion. If your zero is center-dotted and letter-O
\r
64 is not, or if letter-O looks almost rectangular but zero looks more
\r
65 like an American football stood on end (or the reverse), you're
\r
66 probably looking at a modern character display (though the dotted zero
\r
67 seems to have originated as an option on IBM 3270 controllers). If
\r
68 your zero is slashed but letter-O is not, you're probably looking at
\r
69 an old-style ASCII graphic set descended from the default typewheel on
\r
70 the venerable ASR-33 Teletype (Scandinavians, for whom /O is a letter,
\r
71 curse this arrangement). (Interestingly, the slashed zero long
\r
72 predates computers; Florian Cajori's monumental "A History of
\r
73 Mathematical Notations" notes that it was used in the twelfth and
\r
74 thirteenth centuries.) If letter-O has a slash across it and the zero
\r
75 does not, your display is tuned for a very old convention used at IBM
\r
76 and a few other early mainframe makers (Scandinavians curse <emphasis>this</emphasis>
\r
77 arrangement even more, because it means two of their letters collide).
\r
78 Some Burroughs/Unisys equipment displays a zero with a <emphasis>reversed</emphasis>
\r
79 slash. Old CDC computers rendered letter O as an unbroken oval and 0
\r
80 as an oval broken at upper right and lower left. And yet another
\r
81 convention common on early line printers left zero unornamented but
\r
82 added a tail or hook to the letter-O so that it resembled an inverted
\r
83 Q or cursive capital letter-O (this was endorsed by a draft ANSI
\r
84 standard for how to draw ASCII characters, but the final standard
\r
85 changed the distinguisher to a tick-mark in the upper-left corner).
\r
86 Are we sufficiently confused yet?</para>
\r
91 <glossterm>1TBS</glossterm>
\r
93 <para role="accidence">
\r
94 <phrase role="pronounce"></phrase>
\r
95 <phrase role="partsofspeach">n</phrase>
\r
97 <para>The "One True Brace Style"</para>
\r
98 <glossseealso>indent style</glossseealso>
\r
100 </glossentry>
\r
108 </glossary></programlisting>
\r
113 <refsection><info><title>Marking Up Glossary Terms</title></info>
\r
115 <para>That takes care of the glossary database, now you have to get the entries
\r
116 into your document. Unlike bibliography entries, which can be empty, creating
\r
117 <quote>placeholder</quote> glossary entries would be very tedious. So instead,
\r
118 support for <parameter>glossary.collection</parameter> relies on implicit linking.</para>
\r
120 <para>In your source document, simply use <tag>firstterm</tag> and
\r
121 <tag>glossterm</tag> to identify the terms you wish to have included
\r
122 in the glossary. The stylesheets assume that you will either set the
\r
123 <tag class="attribute">baseform</tag> attribute correctly, or that the
\r
124 content of the element exactly matches a term in your glossary.</para>
\r
126 <para>If you're using a <parameter>glossary.collection</parameter>, don't
\r
127 make explicit links on the terms in your document.</para>
\r
129 <para>So, in your document, you might write things like this:</para>
\r
132 <programlisting><para>This is dummy text, without any real meaning.
\r
133 The point is simply to reference glossary terms like <glossterm>0</glossterm>
\r
134 and the <firstterm baseform="1TBS">One True Brace Style (1TBS)</firstterm>.
\r
135 The <glossterm>1TBS</glossterm>, as you can probably imagine, is a nearly
\r
136 religious issue.</para></programlisting>
\r
139 <para>If you set the <parameter>firstterm.only.link</parameter> parameter,
\r
140 only the terms marked with <tag>firstterm</tag> will be links.
\r
141 Otherwise, all the terms will be linked.</para>
\r
145 <refsection><info><title>Marking Up the Glossary</title></info>
\r
147 <para>The glossary itself has to be identified for the stylesheets. For lack
\r
148 of a better choice, the <tag class="attribute">role</tag> is used.
\r
149 To identify the glossary as the target for automatic processing, set
\r
150 the role to <quote><literal>auto</literal></quote>. The title of this
\r
151 glossary (and any other information from the <tag>glossaryinfo</tag>
\r
152 that's rendered by your stylesheet) will be displayed, but the entries will
\r
153 come from the database.
\r
156 <para>Unfortunately, the glossary can't be empty, so you must put in
\r
157 at least one <tag>glossentry</tag>. The content of this entry
\r
158 is irrelevant, it will not be rendered:</para>
\r
161 <programlisting><glossary role="auto">
\r
163 <glossterm>Irrelevant</glossterm>
\r
165 <para>If you can see this, the document was processed incorrectly. Use
\r
166 the <parameter>glossary.collection</parameter> parameter.</para>
\r
168 </glossentry>
\r
169 </glossary></programlisting>
\r
172 <para>What about glossary divisions? If your glossary database has glossary
\r
173 divisions <emphasis>and</emphasis> your automatic glossary contains at least
\r
174 one <tag>glossdiv</tag>, the automic glossary will have divisions.
\r
175 If the <tag>glossdiv</tag> is missing from either location, no divisions
\r
176 will be rendered.</para>
\r
178 <para>Glossary entries (and divisions, if appropriate) in the glossary will
\r
179 occur in precisely the order they occur in your database.</para>
\r
183 <refsection><info><title>Formatting the Document</title></info>
\r
185 <para>Finally, when you are ready to format your document, simply set the
\r
186 <parameter>glossary.collection</parameter> parameter (in either a
\r
187 customization layer or directly through your processor's interface) to
\r
188 point to your global glossary.</para>
\r
190 <para>The stylesheets will format the glossary in your document as if
\r
191 all of the entries implicilty referenced appeared there literally.</para>
\r
194 <refsection><info><title>Limitations</title></info>
\r
196 <para>Glossary cross-references <emphasis>within the glossary</emphasis> are
\r
197 not supported. For example, this <emphasis>will not</emphasis> work:</para>
\r
200 <programlisting><glossentry>
\r
201 <glossterm>gloss-1</glossterm>
\r
202 <glossdef><para>A description that references <glossterm>gloss-2</glossterm>.</para>
\r
203 <glossseealso>gloss-2</glossseealso>
\r
205 </glossentry></programlisting>
\r
208 <para>If you put glossary cross-references in your glossary that way,
\r
209 you'll get the cryptic error: <computeroutput>Warning:
\r
210 glossary.collection specified, but there are 0 automatic
\r
211 glossaries</computeroutput>.</para>
\r
213 <para>Instead, you must do two things:</para>
\r
217 <para>Markup your glossary using <tag>glossseealso</tag>:</para>
\r
220 <programlisting><glossentry>
\r
221 <glossterm>gloss-1</glossterm>
\r
222 <glossdef><para>A description that references <glossterm>gloss-2</glossterm>.</para>
\r
223 <glossseealso>gloss-2</glossseealso>
\r
225 </glossentry></programlisting>
\r
230 <para>Make sure there is at least one <tag>glossterm</tag> reference to
\r
231 <glossterm>gloss-2</glossterm> <emphasis>in your document</emphasis>. The
\r
232 easiest way to do that is probably within a <tag>remark</tag> in your
\r
233 automatic glossary:</para>
\r
236 <programlisting><glossary role="auto">
\r
237 <remark>Make sure there's a reference to <glossterm>gloss-2</glossterm>.</remark>
\r
239 <glossterm>Irrelevant</glossterm>
\r
241 <para>If you can see this, the document was processed incorrectly. Use
\r
242 the <parameter>glossary.collection</parameter> parameter.</para>
\r
244 </glossentry>
\r
245 </glossary></programlisting>
\r
projects / working / Evergreen.git / blob