From 81e14b9ee10012e60b7da570b59c943b4c9665aa Mon Sep 17 00:00:00 2001 From: Norman Walsh Date: Sun, 6 Jan 2002 19:21:51 +0000 Subject: [PATCH] Added documentation --- xsl/params/bibliography.collection.xml | 82 +++++++++++- xsl/params/glossary.collection.xml | 171 ++++++++++++++++++++++++- 2 files changed, 243 insertions(+), 10 deletions(-) diff --git a/xsl/params/bibliography.collection.xml b/xsl/params/bibliography.collection.xml index df1781e87..2e69e7ddd 100644 --- a/xsl/params/bibliography.collection.xml +++ b/xsl/params/bibliography.collection.xml @@ -14,11 +14,83 @@ Description -Tired of copying bibliography entries from one document to another? -Now you can maintain a central bibliography and let the stylesheets do -the copying for you. This parameter identifies the file (by URI reference) -that contains your complete bibliography collection. - +Maintaining bibliography entries across a set of documents is tedious, time +consuming, and error prone. It makes much more sense, usually, to store all of +the bibliography entries in a single place and simply extract +the ones you need in each document. + +That's the purpose of the +bibliography.collection parameter. To setup a global +bibliography database, follow these steps: + +First, create a stand-alone bibliography document that contains all of +the documents that you wish to reference. Make sure that each bibliography +entry (whether you use biblioentry or bibliomixed) +has an ID. + +My global bibliography, ~/bibliography.xml begins +like this: + + + +References + +XML 1.0Tim Bray, +Jean Paoli, C. M. Sperberg-McQueen, and Eve Maler, editors. +Extensible Markup +Language (XML) 1.0 Second Edition. +World Wide Web Consortium, 2000. + + +NamespacesTim Bray, +Dave Hollander, +and Andrew Layman, editors. +Namespaces in +XML. +World Wide Web Consortium, 1999. + + + + +]]> + + +When you create a bibliography in your document, simply +provide empty bibliomixed +entries for each document that you wish to cite. Make sure that these +elements have the same ID as the corresponding real +entry in your global bibliography. + +For example: + + +Bibliography + + + +Donald E. Knuth. Computers and +Typesetting: Volume B, TeX: The Program. Addison-Wesley, +1986. ISBN 0-201-13437-3. + + + +]]> + + +Note that it's perfectly acceptable to mix entries from your +global bibliography with normal entries. You can use +xref or other elements to cross-reference your +bibliography entries in exactly the same way you do now. + +Finally, when you are ready to format your document, simply set the +bibliography.collection parameter (in either a +customization layer or directly through your processor's interface) to +point to your global bibliography. + +The stylesheets will format the bibliography in your document as if +all of the entries referenced appeared there literally. diff --git a/xsl/params/glossary.collection.xml b/xsl/params/glossary.collection.xml index 5030d5551..003c08502 100644 --- a/xsl/params/glossary.collection.xml +++ b/xsl/params/glossary.collection.xml @@ -16,13 +16,174 @@ Description -Tired of manually maintaining glossaries for multiple documents? -Now you can maintain a central glossary and let the stylesheets do -the copying for you. This parameter identifies the file (by URI reference) -that contains your complete glossary collection. +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: + + + + + + +EricRaymond +Jargon File 4.2.3 (abridged) +Just some test data + + +0 + + +0 + +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 this +arrangement even more, because it means two of their letters collide). +Some Burroughs/Unisys equipment displays a zero with a reversed +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? + + + + +1TBS + + + +n + +The "One True Brace Style" +indent style + + + + + + + + + +]]> + + + + +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: + + +This is dummy text, without any real meaning. +The point is simply to reference glossary terms like 0 +and the One True Brace Style (1TBS). +The 1TBS, as you can probably imagine, is a nearly +religious issue.]]> + + +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. -THIS IS EXPERIMENTAL. IT PROBABLY DOESN'T WORK +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: + + + + +Irrelevant + +If you can see this, the document was processed incorrectly. Use +the glossary.collection parameter. + + +]]> + + +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. + -- 2.40.0