doc/xslt/params/glossary.collection.xml

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