| OLD | NEW |
|---|
| (Empty) |
| 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 <?xml version="1.0" encoding="utf-8"?> | |
| 45 <!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"> | |
| 48 <glossary> | |
| 49 <glossaryinfo> | |
| 50 <editor><firstname>Eric</firstname><surname>Raymond</
surname></editor> | |
| 51 <title>Jargon File 4.2.3 (abridged)</title> | |
| 52 <releaseinfo>Just some test data</releaseinfo> | |
| 53 </glossaryinfo> | |
| 54 | |
| 55 <glossdiv><title>0</title> | |
| 56 | |
| 57 <glossentry> | |
| 58 <glossterm>0</glossterm> | |
| 59 <glossdef> | |
| 60 <para>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 <emphasis>this
</emphasis> | |
| 77 arrangement even more, because it means two of their letters collide). | |
| 78 Some Burroughs/Unisys equipment displays a zero with a <emphasis>reversed&
lt;/emphasis> | |
| 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?</para> | |
| 87 </glossdef> | |
| 88 </glossentry> | |
| 89 | |
| 90 <glossentry> | |
| 91 <glossterm>1TBS</glossterm> | |
| 92 <glossdef> | |
| 93 <para role="accidence"> | |
| 94 <phrase role="pronounce"></phrase> | |
| 95 <phrase role="partsofspeach">n</phrase> | |
| 96 </para> | |
| 97 <para>The "One True Brace Style"</para> | |
| 98 <glossseealso>indent style</glossseealso> | |
| 99 </glossdef> | |
| 100 </glossentry> | |
| 101 | |
| 102 <!-- ... --> | |
| 103 | |
| 104 </glossdiv> | |
| 105 | |
| 106 <!-- ... --> | |
| 107 | |
| 108 </glossary></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 linkin
g.</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><para>This is dummy text, without any real meaning. | |
| 133 The point is simply to reference glossary terms like <glossterm>0</glos
sterm> | |
| 134 and the <firstterm baseform="1TBS">One True Brace Style (1TBS)</firstte
rm>. | |
| 135 The <glossterm>1TBS</glossterm>, as you can probably imagine, is a n
early | |
| 136 religious issue.</para></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><glossary role="auto"> | |
| 162 <glossentry> | |
| 163 <glossterm>Irrelevant</glossterm> | |
| 164 <glossdef> | |
| 165 <para>If you can see this, the document was processed incorrectly. Use | |
| 166 the <parameter>glossary.collection</parameter> parameter.</para&g
t; | |
| 167 </glossdef> | |
| 168 </glossentry> | |
| 169 </glossary></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>A relative path in the parameter is interpreted in one | |
| 191 of two ways:</para> | |
| 192 <orderedlist numeration="loweralpha"> | |
| 193 <listitem> | |
| 194 <para>If the parameter <literal>glossterm.auto.link</literal> | |
| 195 is set to zero, then the path is relative to the file containing | |
| 196 the empty <tag>glossary</tag> element in the document.</para> | |
| 197 </listitem> | |
| 198 <listitem> | |
| 199 <para>If the parameter <literal>glossterm.auto.link</literal> | |
| 200 is set to non-zero, then the path is relative to the file containing | |
| 201 the first inline <tag>glossterm</tag> or | |
| 202 <tag>firstterm</tag> in the document to be linked.</para> | |
| 203 </listitem> | |
| 204 </orderedlist> | |
| 205 <para>Once the collection file is opened by the first instance described | |
| 206 above, it stays open for the current document | |
| 207 and the relative path is not reinterpreted again.</para> | |
| 208 | |
| 209 <para>The stylesheets will format the glossary in your document as if | |
| 210 all of the entries implicilty referenced appeared there literally.</para> | |
| 211 </refsection> | |
| 212 | |
| 213 <refsection><info><title>Limitations</title></info> | |
| 214 | |
| 215 <para>Glossary cross-references <emphasis>within the glossary</emphasis> are | |
| 216 not supported. For example, this <emphasis>will not</emphasis> work:</para> | |
| 217 | |
| 218 <informalexample> | |
| 219 <programlisting><glossentry> | |
| 220 <glossterm>gloss-1</glossterm> | |
| 221 <glossdef><para>A description that references <glossterm>gloss
-2</glossterm>.</para> | |
| 222 <glossseealso>gloss-2</glossseealso> | |
| 223 </glossdef> | |
| 224 </glossentry></programlisting> | |
| 225 </informalexample> | |
| 226 | |
| 227 <para>If you put glossary cross-references in your glossary that way, | |
| 228 you'll get the cryptic error: <computeroutput>Warning: | |
| 229 glossary.collection specified, but there are 0 automatic | |
| 230 glossaries</computeroutput>.</para> | |
| 231 | |
| 232 <para>Instead, you must do two things:</para> | |
| 233 | |
| 234 <orderedlist> | |
| 235 <listitem> | |
| 236 <para>Markup your glossary using <tag>glossseealso</tag>:</para> | |
| 237 | |
| 238 <informalexample> | |
| 239 <programlisting><glossentry> | |
| 240 <glossterm>gloss-1</glossterm> | |
| 241 <glossdef><para>A description that references <glossterm>gloss
-2</glossterm>.</para> | |
| 242 <glossseealso>gloss-2</glossseealso> | |
| 243 </glossdef> | |
| 244 </glossentry></programlisting> | |
| 245 </informalexample> | |
| 246 </listitem> | |
| 247 | |
| 248 <listitem> | |
| 249 <para>Make sure there is at least one <tag>glossterm</tag> reference to | |
| 250 <glossterm>gloss-2</glossterm> <emphasis>in your document</emphasis>. The | |
| 251 easiest way to do that is probably within a <tag>remark</tag> in your | |
| 252 automatic glossary:</para> | |
| 253 | |
| 254 <informalexample> | |
| 255 <programlisting><glossary role="auto"> | |
| 256 <remark>Make sure there's a reference to <glossterm>gloss-2</glos
sterm>.</remark> | |
| 257 <glossentry> | |
| 258 <glossterm>Irrelevant</glossterm> | |
| 259 <glossdef> | |
| 260 <para>If you can see this, the document was processed incorrectly. Use | |
| 261 the <parameter>glossary.collection</parameter> parameter.</para&g
t; | |
| 262 </glossdef> | |
| 263 </glossentry> | |
| 264 </glossary></programlisting> | |
| 265 </informalexample> | |
| 266 </listitem> | |
| 267 </orderedlist> | |
| 268 </refsection> | |
| 269 | |
| 270 </refsection> | |
| 271 </refentry> | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 1394993002:
Doing some cleanup. (Closed)
Base URL: https://github.com/dart-lang/www.dartlang.org.git@master