X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/793149f04ce52bf75dc4efb7b83a3f8ed30d1fff..35ec793690104efdd610964d255302a0310a2daf:/doc/xslt/params/glossary.collection.xml diff --git a/doc/xslt/params/glossary.collection.xml b/doc/xslt/params/glossary.collection.xml deleted file mode 100644 index 6f9828bd..00000000 --- a/doc/xslt/params/glossary.collection.xml +++ /dev/null @@ -1,252 +0,0 @@ - - -glossary.collection -string - - -glossary.collection -Name of the glossary collection file - - - - - - - - -Description - -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 -extract the ones you need in each document. - -That's the purpose of the -glossary.collection parameter. To setup a global -glossary database, follow these steps: - -Setting Up the Glossary Database - -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. - -Here's an example glossary: - - - -<?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> - - - - -Marking Up Glossary Terms - -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 -placeholder glossary entries would be very tedious. So instead, -support for glossary.collection relies on implicit linking. - -In your source document, simply use firstterm and -glossterm to identify the terms you wish to have included -in the glossary. The stylesheets assume that you will either set the -baseform attribute correctly, or that the -content of the element exactly matches a term in your glossary. - -If you're using a glossary.collection, don't -make explicit links on the terms in your document. - -So, in your document, you might write things like this: - - -<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> - - -If you set the firstterm.only.link parameter, -only the terms marked with firstterm will be links. -Otherwise, all the terms will be linked. - - - -Marking Up the Glossary - -The glossary itself has to be identified for the stylesheets. For lack -of a better choice, the role is used. -To identify the glossary as the target for automatic processing, set -the role to auto. The title of this -glossary (and any other information from the glossaryinfo -that's rendered by your stylesheet) will be displayed, but the entries will -come from the database. - - -Unfortunately, the glossary can't be empty, so you must put in -at least one glossentry. The content of this entry -is irrelevant, it will not be rendered: - - -<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> - - -What about glossary divisions? If your glossary database has glossary -divisions and your automatic glossary contains at least -one glossdiv, the automic glossary will have divisions. -If the glossdiv is missing from either location, no divisions -will be rendered. - -Glossary entries (and divisions, if appropriate) in the glossary will -occur in precisely the order they occur in your database. - - - -Formatting the Document - -Finally, when you are ready to format your document, simply set the -glossary.collection parameter (in either a -customization layer or directly through your processor's interface) to -point to your global glossary. - -The stylesheets will format the glossary in your document as if -all of the entries implicilty referenced appeared there literally. - - -Limitations - -Glossary cross-references within the glossary are -not supported. For example, this will not work: - - -<glossentry> -<glossterm>gloss-1</glossterm> -<glossdef><para>A description that references <glossterm>gloss-2</glossterm>.</para> -<glossseealso>gloss-2</glossseealso> -</glossdef> -</glossentry> - - -If you put glossary cross-references in your glossary that way, -you'll get the cryptic error: Warning: -glossary.collection specified, but there are 0 automatic -glossaries. - -Instead, you must do two things: - - - -Markup your glossary using glossseealso: - - -<glossentry> -<glossterm>gloss-1</glossterm> -<glossdef><para>A description that references <glossterm>gloss-2</glossterm>.</para> -<glossseealso>gloss-2</glossseealso> -</glossdef> -</glossentry> - - - - -Make sure there is at least one glossterm reference to -gloss-2 in your document. The -easiest way to do that is probably within a remark in your -automatic glossary: - - -<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> - - - - - - -