summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gloss/gloss.tex
blob: 9e60fad71665276afa8cb814aae285eb640d2c54 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
% +--------------------------------------------------+
% | Typeset this file to get the documentation.      |
% +--------------------------------------------------+
%
% (c) 1998 Jose Luis Diaz, 1999-2002 Jose Luis Diaz and Javier Bezos.
% All Rights Reserved.
%
% This file is part of the gloss distribution release 1.5.2
% -----------------------------------------------------------
%
% This file can be redistributed and/or modified under the terms
% of the LaTeX Project Public License Distributed from CTAN
% archives in directory macros/latex/base/lppl.txt; either
% version 1 of the License, or any later version.

\def\fileversion{1.5.2}
\def\docdate{July 26, 2002}

\documentclass{ltxguide}
\usepackage{hyperref}

\title{The \textsf{gloss} Package\footnote{The
\textsf{gloss} package is currently at version \fileversion. \copyright{} 
1998 Jose Luis Diaz,
1999-2001 Jose Luis Diaz and Javier Bezos. All Rights Reserved.}}

\author{Jose Luis D\'{\i}iaz\\Javier Bezos\footnote{For bug reports, comments and
suggestions go to \href{http://www.texytipografia.com/contact.php}%
{http://www.texytipografia.com/contact.php}.  New \texttt{.bst} styles
are also welcome.  English is not my strong point, so contact me when
you find mistakes in the manual.  Other packages by Javier Bezos:
\textsf{accents, tensind, esindex, titlesec, titletoc, dotlessi}.}}

\date{\docdate}

\addtolength{\topmargin}{-3pc}
\addtolength{\textwidth}{6pc}
\addtolength{\oddsidemargin}{-2pc}
\addtolength{\textheight}{7pc}

\raggedright
\parindent1em

\newcommand{\gloss}{\textsf{gloss}}
\newcommand{\bibTeX}{\textsc{Bib}\TeX}

\begin{document}

\maketitle

\textsf{Gloss} is a package which allows the creation of glossaries 
using \bibTeX. With this approach, the user writes a database of terms 
and definitions using a file format much like the bibliographic 
databases.  Then he inserts in the \LaTeX{} document a command 
|\gloss{<key>}| for selecting which entries he wants to appear in the 
glossary.  These keys are written in an auxiliar file when \LaTeX{} is 
run on the document.  Then, running \bibTeX{} these entries are 
extracted from the database and collected in alphabetical order in a 
file.  The next run of \LaTeX{} read this file and inserts it in the 
appropiate point of the document, typesetting the desired glossary or 
glossaries.

The process is much like the mechanism for including the bibliographic
references. This approach has several advantages:
\begin{enumerate}
\item \bibTeX{} is available in every platform where \TeX{} is.
\item Glossary entries can be stored in databases, and you needn't
  rewrite the definitions.
\item There are a lot of tools for managing \bibTeX{} databases.
\item \bibTeX{} can sort the entries and group them; furthermore,
  \bibTeX-8 can sort correctly the entries in non-English
  languages. (In fact, this is the main raison which the package
  was first developped for.)
\item \bibTeX{} is a programable tool and you can define your own 
  styles for acronyms, symbols, and so on, or changing its default 
  behaviour.  \textsf{Gloss} styles are pretty simples and creating
  new ones is not difficult.
\end{enumerate}

Of course, there also disavantages---for example, you cannot
select sorting entries word by word or letter by letter, at least
at present.

The gloss{} bundle includes the \textsf{gloss}.sty package, a 
\textsf{glsplain}.bst style, a \textsf{glsbase}.bib database, and a 
\texttt{sample.tex} file with its \texttt{sample.bib} database 
(and, of course, the \texttt{readme} file and this manual).

\section{The data files}

If you know \bibTeX, you will find this section easy to understand.
A data file contains a set of records defining terms, and its
name must have the extension \texttt{.bib}. Every entry has the
following format:
\begin{verbatim}
@gd{gnu,
  word = {gnu},
  definition = {Extrange animal}
}
\end{verbatim}

Here
\begin{itemize}
\item |gnu| is a key identifying the record;
\item |word| is the word which will be used as headword and in the 
  text; and
\item |definition| is the definition printed in the glossary.
\end{itemize}

Here is the description of the available fields, and when they are used
\begin{description}
\item[word] Required.  It should be given always as it would be 
  written at the middle of a sentence.  The basic style 
  \textsf{glsplain} converts its first letter to uppercase for use after 
  a period.  In the generated glossary, entries with the 
  same initial are grouped, preceded by a heading with that letter.

\item[definition] Required.  The definition can be as long an you 
  want, but you should note that implicit paragraphs (those with a 
  blank line) are ignored and a |\par| would be necessary.  The final 
  period should be omitted because it is supplied later (and sometimes it 
  will be replaced by a comma).

\item[short] Optional. A short form. It could be a symbol, an
  acronym, etc. depending on the nature of the glossary.

\item[sort-word] Optional.  If present, this field will be used to 
sort the entries.  It is useful in greek symbols and signs, for 
example.

\item[group] Optional.  This field should consist in an uppercase 
  letter and is intended for entries not beginning (or not containing) 
  letters.  Entries with the same |group| are gathered in the glossary 
  under a single heading and sorted in the whole glossary using this 
  letter, with entries without |group| placed as if they had a group 
  key of |L|.  Using both |sort-word| and this field allows grouping, 
  say, greek symbols, numbers, signs and the like under seperate 
  headings.  More on that later.

\item[heading] Optional. It forces an entry to be listed under the
  given heading. Useful in non-English languages when
  letters with diacriticals are used (even with \bibTeX-8):
\begin{verbatim}
@gd{gnu,
  word = "{\'A}nimo",
  definition = "...",
  heading = "A"}
\end{verbatim}
This field is uncompatible with |group|.

\end{description}

The |@gd| entry type is the only available currently in |glsplain|.  
|@glossdef| is a synonymous.

The default |crossref| field is available, but in glossaries is mostly 
unpractical except in a few cases (for example, in a list of symbols 
with the same greek letter with many meanings).

\section{Basic commands}

\begin{decl}
|\makegloss|
\end{decl}

This command in the preamble tells \gloss{} to create a glossary.

\begin{decl}
|\gloss{<key>}|
\end{decl}

Similar to |\cite|.  It writes a ``citation'' to the auxiliary file 
|.gls.aux|.  Sadly, this double extension is necessary because 
\bibTeX{} requires the input file to be named with the |.aux| 
extension.  Below is explained how MS-DOS users can work around that.
Note that this file is not reread by the document, it just
provides information to \bibTeX\ of terms cited.

\begin{decl}
|\printgloss{<databases>}|
\end{decl}

Similar to |\bibliography|.  It prints the glossary stored into the 
|.gls.bbl| file generated by \bibTeX{} from |.gls.aux|.

In this basic interface the \textsf{glsplain} style is used always.

\section{The generated glossary}

The steps to generate and use the glossary are:
\begin{itemize}
\item \LaTeX{} the document (let's call it |file.tex|),
\item \bibTeX\ the |.gls.aux| file (i.e., |bibtex file.gls|),
\item \LaTeX{} the document again, and
\item \LaTeX{} again if there are unresolved cross references.
\end{itemize}

Once \LaTeX{}ed the document, and \bibTeX{}ed the |.gls.aux| file,
you will get the glossary in the |.gls.bbl| with the following \TeX{}
format:
\begin{itemize}

\item the whole glossary is enclosed in the |thegloss| environment,
  which just prints the sectioning heading whith the |\glossname| title;

\item a series of |\glossheading|s (or |\glossgroup|s) commands
  and |glossitem|s environments. Note that gloss items are not
  commands but environments. The |glossitem*| environment means that
  the definition of the entry ends with a period.

\end{itemize}

\section{The whole thing}

Most of the formatting is done by the package and not by \bibTeX. The 
\textsf{glsplain} style provides two forms, sometimes three, of 
terms: the basic form as given in |word| to be used in the text, 
and probably as headword, the second one is |word| with the first 
letter uppercased to be used at the beginning of a sentence; and only 
if |short| was included, a short form.

Not surprisingly, the syntax of the \gloss{} commands is very
alike to that of bibliographies with some touches from that
of indexes.

\subsection{Package options}

\begin{decl}
|refpages|
\end{decl}

The number of the first page where the term is referred to, is
appended to the gloss entry.

\subsection{Multiple glossaries}

\begin{decl}
|\makegloss|\\
|\newgloss{<name>}{<suffix>}{<title>}{<style>}|
\end{decl}

For defining a new glossary use |\newgloss|. The |\makegloss|
command is just a synonymous with
\begin{verbatim}
\newgloss{default}{.gls}{\glossname}{glsplain}
\end{verbatim}
Note that the suffix does include the dot.

MS-DOS users must use |\newgloss| instead of |\makegloss|, and
a document name with at most seven letters. For instance:
\begin{verbatim}
\newgloss{default}{G}{\glossname}{glsplain}
\end{verbatim}
Note that, in this case, the suffix does not include the dot
(this way we avoid double extensions).

\begin{decl}
|\printgloss[<name>]{<databases>}|
\end{decl}

Prints the |<name>| glossary. By default, the |default| one
is printed. 

\subsection{The \texttt{\string\gloss} command}

\begin{decl}
|\gloss[<options>]{<key>}|
\end{decl}

Possible options are:
\begin{itemize}
\item |nocite| makes the command behave in the same fashion
  as |\nocite|.  For example, with |\gloss[nocite]{*}| all entries of 
  the databases are included in the glossary.\footnote{The command 
  |\string\onlygloss| is a deprecated synonymous with
  |\string\gloss[nocite]|.}

\item |refpage| tells \gloss{} to ignore previous references to pages.
  Sometimes you say things like ``...at the end of the chapter, we will 
  introduce the concept of...''; when the concept is actually
  introduced you should use this option.

\item |<name>| of the glossary file where the key is written,
  as defined by |\newgloss|. The key will be written into that
  glossary. If there is no |<name>| it defaults to |default|.
\end{itemize}

The following options control the format of the term in the text.

\begin{itemize}

\item |word| prints the term exactly as given in the |word| field.

\item |Word| prints the term as given in the |word| field, but 
  with the first letter uppercased.\footnote{%
  The command |\string\Gloss| is a deprecated synonymous with
  |\string\gloss[Word]|.}

\begin{verbatim}
 ...discovered. \gloss[Word]{spectroscopy} became one of the most...
\end{verbatim}

\item |short| prints the short form, provided the bib file defines it
  (if not a warning is reported).

\item |Long| prints a combination of |Word| and |short|: ``Word 
  (short)''.

\item |long| prints a combination of |word| and |short|: ``word 
(short)''.  For example, the very first time an acronym is used:
\begin{verbatim}
...and the proposals made by the \gloss[long]{iupac} provide...
\end{verbatim}
  Of course, you may want the following references to be in the short
  form; just define
\begin{verbatim}
\newcommand{\acronym}[2][]{\gloss[short,#1]{#2}}
\end{verbatim}

\end{itemize} The former (|nocite| and |refpage|) are built in, 
|<name>|s are created by |\newgloss|, and the latter are created by 
the package with |\setglosstext|; if no option defined by 
|\setglosstext| is included, it defaults to |word|.

\begin{decl}
|\setglosstext{<option-name>}{<format>}| \quad (3 parameters)\\
|\ifglossshort{<format>}| \qquad |\ifglossshort*{<format>}|
\end{decl}

|\setglosstext| sets how entries are printed in the main text by 
|\gloss|, where |<option-name>| is the name to be used in the optional 
argument of |\gloss|.  There are five predefined formats, described 
above, which you may redefine or complement with new defined ones.  In 
|<format>| there are three available arguments, which are defined 
implicitly: 
|#1| is |word|, |#2| is |word| with its initial uppercased, and |#3| 
is the |short| field.  Thus, the package does the following:
\begin{verbatim}
\setglosstext{word}{#1}
\setglosstext{Word}{#2}
\setglosstext{short}{\ifglossshort*{#3}{}}
\setglosstext{long}{#1\ifglossshort*{ (#3)}{}}
\setglosstext{Long}{#2\ifglossshort*{ (#3)}{}}
\end{verbatim}
Use is made of |\ifglossshort| which takes the first argument if the 
short form exists, and the second one if does not exist.  In the 
latter case, that is done silently in the unstarred version, but with 
an error in the starred one.

\subsection{Glossary layout}

\begin{decl}
|\glossheading{<format>}|
\end{decl}

Sets how the headings are formatted; it is redefined with
|\renewcommand|. For example:
\begin{verbatim}
\renewcommand\glossheading[1]{%
  \stopglosslist
  \subsection*{#1}}
\end{verbatim}

\begin{decl}
|\setglossgroup{<group>}{<heading>}|
\end{decl}

Sets the heading corresponding to entries grouped by \textsf{glsplain} 
under the same |group| key (and preceded by |\glossgroup|, which in 
turn calls |\glossheading|).
\begin{verbatim}
\setglossgroup{C}{Signs}
\end{verbatim}

\begin{decl}
|\setglosslabel{<format>}| \quad (3 parameters)
\end{decl}

Sets which of the three forms are printed as label in the gloss items and
some other optional formatting.

The package does:
\begin{verbatim}
\setglosslabel{\sffamily\bfseries#1\ifglossshort{ (#3)}{}}
\end{verbatim}

\begin{decl}
|thegloss|
\end{decl}

By default, the main environment just prints the gloss title.
You may change its definition.

\begin{decl}
|glosslist|\\
|\stopglosslist|
\end{decl}

You usually won't see the |glosslist| environnment. It is automatically
started by |glossitem| if necessary. You may stop it with the 
|\stopglosslist|. That's so done to interact with the format
of the heading for each letter group. The above example of 
|\glossheading| uses it because sectioning commands cannot be
used inside lists; this way, the list is stopped, the title is
printed, and the following |glossitem| restarts the list. If
you say:
\begin{verbatim}
\renewcommand{\glossheading}[1]{}
\end{verbatim}
the whole glossary is printed in a single list (with no unwanted
space between letter groups).

\textsf{Gloss} provides its own format for |glosslist|
(simply because the authors like it) with a |\glosshang| length
to adjust the left margin, but you may change its definition.

\begin{decl}
|glossitem|\\
|glossitem*|
\end{decl}

Its |\begin| consists of an |\item| and some additional stuff.  Its 
|\end| adds a period (except in the starred version) or the page 
number.  You should not modify this environment, except if you want a 
format not based in a list environment.

Here is an example of how to modify the layout of the glossary:
\begin{verbatim}
\setglosslabel{#2}

\renewcommand{\glossheading}[1]{%
  \stopglosslist  % -- Don't forget that!
  \vspace{1pc}%
  {\large\centering\bfseries#1\par}}

\renewenvironment{glosslist}
  {\begin{description}}
  {\end{description}}
\end{verbatim}

\begin{decl}
|\glosspage|\\
|\xglosspage|
\end{decl}

This command is used to print the page at the end of the gloss entry 
with |refpages|.  If the entry ends with a period, |\xglosspage| is 
used, which by default just maps to |\glosspage|.  You may redefine them 
with |\renewcommand|:

\begin{verbatim}
\renewcommand{\glosspage}[1]{. (See page~#1)}
\renewcommand{\xglosspage}[1]{ (See page~#1)}
\end{verbatim}


\section{Order of items}

Now we explain how \bibTeX{} sorts and groups entries. Firstly, the
necessary values are assigned, if necessary. The |group| field is
used, as stated above, for entries consisting of non alphabetical
terms, and differents steps are followed depending on whether
this field exists or not.

If |group| is not present, then
\begin{itemize}
\item |sort-word|, if omitted, is |word| lowercased with
  non alphabetical signs removed.

\item |heading|, if omitted, is the first letter in
  |word|.
\end{itemize}
If |group| is present, then
\begin{itemize}
\item |sort-word|, if omitted, is |word| lowercased with
  non alphabetical signs \textit{not} removed.

\item |heading| is not used. 
\end{itemize}

Now, entries can be sorted.  First, they are ordered by |group|, and 
then, inside each group, by |sort-word|.  In fields with |group| and 
no |sort-word| the ASCII codes are used.  No further sortening is 
done.  Finally, entries are grouped: first, consecutive entries with 
the same |group| field; then, consecutive entries whose |group| is "L" 
and with the same |heading| field.  Note that |group| sorts and 
groups, |sort-word| just sorts, and |heading| just groups.

Now, let's answer the following simple question: When should I use 
|heading| and |sort-word|?  If the word begins with a letter with 
diacritical mark alphabetized under the letter without diacritical 
mark (a fairly frequent case), use heading, does not matter you are 
using \bibTeX{} or \bibTeX 8:
\begin{verbatim}
@gd{ecole,
  word = "{\'e}cole",
  definition = "...",
  heading = "E"
}
\end{verbatim}
(\texttt{\'ecole} and \texttt{{'e}cole} are allowed, too).

If the word begins with a letter which is placed under a heading of 
its own, use |sort-word| in \bibTeX{} and nothing in \bibTeX8 
(provided a correct sorting file is provided, which is not the case 
for many languages):
\begin{verbatim}
@gd{nname,
  word = "{\~n}ame",
  definition = "...",
  sort-word = "nzzame"
}
\end{verbatim}
in 7-bits versions.  In 8-bits version, you may set |word| as 
\texttt{\~name} and suppress the |sort-word| field.

Anyway, if you are using a 7-bits version you may want using both fields:
\begin{verbatim}
@gd{innigo,
  word = "{\'I}\~nigo",
  definition = "...",
  heading = "I",
  sort-word = "Inzzigo"
}
\end{verbatim}

Finaly, \textsf{gloss} provides inside the |thegloss| environment the 
|\+zz+| command expanding to nothing, where |zz| is any text helping 
in sorting entries (usualy |zz|); this way, |sort-field| is not 
necessary in most of cases:
\begin{verbatim}
@gd{nname,
  word = "{\~n\+zz+}ame",
  definition = "..."
}
\end{verbatim}
An example in Swedish is |\+zzx+\r{a}|, in Czech 
|{\v{c}\+zz+}|, and in Breton (8-bits) |\+n+\~n|.  (Of course, 
\bibTeX{} could translate from a readable form to one for 
alphabetizing.  That should be done in a future.) Using either 
|sort-word| or |\+zz+| is a question of personal taste; One of us [JB] 
uses |sort-word| while the other [JLDA] prefers 
\bibTeX8.  This syntax is not compliant with the \LaTeX\ interface 
guidelines (use braces or brackets always) but it's short, which was 
the main goal; this feature is mostly unsuportted, however.

\section{Complements}

\subsection{The \textsf{glsbase} database}

This database defines some useful strings which can be used
in other databases. Currently, it only includes a set of
strings named |alphasort|, |betasort|, etc. to be used
in the |sort-word| field to provide the right order of
greek symbols. (They are defined as |"01"| , |"02"|, etc.)

\subsection{The \textsf{glsshort} style}

This style is provided for acronym lists. It sorts and creates
headings using the |short| filed. A new |sort-short| can be used
to fine tune the order of entries (this field will be ignored
in the \textsf{glsplain} style). However, note that the
printed form still follows the conventions given above, and
you should use the |short| specifier in |\cite|, and
|\setglosslabel|.

\subsection{Compatibility with \textsf{hyperref}}

If the \textsf{hyperref} package is loaded, links from the
word to the entry will be created. You can control
the appearance of gloss links with the following macros:
|\glosslinkborder|, |\glosslinkcolor|,
|\glosslinkbordercolor| (which correspond to |pdfborder|,
|linkcolor| and |linkbordercolor|); you can change
them with |\renewcommand|.

\subsection{The sample file}

Once installed \gloss{} you should be able to typeset the
|sample.tex| file, which will enlighten the usage
of this package --- \LaTeX{} to write the auxiliary file, \bibTeX{}
to create the glossary, \LaTeX{} to define the labels, and \LaTeX{}
to see the final result. Disclaimer: its text is in Spanish.

\subsection{Backward uncompatibility}

Version 0.1 beta had a different syntax for the |\gloss| 
command. The old syntax |\gloss[<word>]{<key>}| does not work
and |<word>\gloss[nocite]{<key>}| should be used instead. The
|\glossstyle| command has been removed and its functionality
merged into |\newgloss|.

\subsection{Language support}

The following package options provide translation of the glossary 
heading and page abbreviation: |basque|, |catalan|, |danish|, |dutch|, 
|french|, |german|, |italian|, |portuguese| (and |brazilian|), 
|russian| (any encoding), |polish|, |spanish| and |swedish|.  
Translations to other languages are welcome.

\end{document}