diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex | 1192 |
1 files changed, 909 insertions, 283 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex b/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex index 3c1aed60ecf..c8d9905bde2 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex @@ -8,376 +8,1002 @@ \usepackage{courier} \usepackage{xr-hyper} \fi + +\usepackage{alltt} +\usepackage{pifont} +\usepackage{array} + \usepackage[colorlinks,pdfauthor={Nicola L.C. Talbot}, pdftitle={The glossaries package: a guide for beginners}]{hyperref} +\usepackage[nomain]{glossaries} + +\newcommand*{\yes}{\ding{52}} +\newcommand*{\no}{\ding{56}} \title{The glossaries package: a guide for beginners} \author{Nicola L.C. Talbot} -\date{2014-01-20} +\date{2014-03-06} + +\ifpdf + \externaldocument{glossaries-user} +\fi -\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}} -\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}} +\makeatletter +\newcommand*{\optionlabel}[1]{% + \@glstarget{option#1}{}\textbf{Option~#1}} +\makeatother -\ifpdf\externaldocument{glossaries-user}\fi +\newcommand*{\opt}[1]{\hyperlink{option#1}{Option~#1}} +\newcommand*{\optsor}[2]{Options~\hyperlink{option#1}{#1} +or~\hyperlink{option#2}{#2}} +\newcommand*{\optsand}[2]{Options~\hyperlink{option#1}{#1} +and~\hyperlink{option#2}{#2}} \begin{document} \maketitle \begin{abstract} -This document is a brief guide to the \styfmt{glossaries} package for -beginners who find the size of the main user manual daunting and, as -such, it only covers the basics. For more advanced topics, see the -\docref{main user manual}{glossaries-user}. +This document is a brief guide to the \styfmt{glossaries} package +for beginners who find the size of the main user manual daunting +and, as such, it only covers the basics. For brevity some options to +the commands described here are omitted. For a~more detailed guide, +see the \docref{main user manual}{glossaries-user}. \end{abstract} \tableofcontents -\section{What Do I Need?} -\label{requirements} - -You need to have the \styfmt{glossaries} package installed. This and -all dependent packages are contained in both the TeX~Live and MikTeX -distributions. Use your distribution's update manager to ensure you -have an up-to-date version. These packages can also be downloaded -from CTAN if you don't have them installed. See -\urlfootref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=installthings}{\qt{Installing -things on a (La)TeX System}} for further assistance. - -In addition, you need an indexing application. The \sty{glossaries} -package is configured to use either \app{makeindex} or \app{xindy}. -\app{Makeindex} should be available on all \TeX\ systems. It's -possible you may not have \app{xindy} installed, but it can be -downloaded from the \urlfootref{http://www.xindy.org/}{xindy home -page}. MiKTeX users may find the -\urlfootref{http://www.latex-community.org/forum/viewtopic.php?f=51&t=5383}{Xindy for MiKTeX} thread on the LaTeX Community Forum helpful. - -The \sty{glossaries} package provides a helper Perl script -called \app{makeglossaries} which will act as an interface to -\app{makeindex} or \app{xindy}. If you want to use -\app{makeglossaries} or \app{xindy}, you need to have Perl -installed. If you don't have Perl installed, you can still use -\styfmt{glossaries} but you can only use it with \app{makeindex}. - -\section{Getting Started} -\label{start} - -The most obvious things to do is to remember to load the -\sty{glossaries} package: +\section{Defining Terms} +\label{sec:defterm} + +When you use the \sty{glossaries} package, you need to define +glossary entries in the document preamble. These entries could be +a~word, phrase, acronym or symbol. They're usually accompanied by +a~description, which could be a short sentence or an in-depth +explanation that spans multiple paragraphs. The simplest method of +defining an entry is to use: +\begin{definition} +\begin{alltt} +\cs{newglossaryentry}\marg{label} +\verb|{| + name=\marg{name}, + description=\marg{description}, + \meta{other options} +\verb|}| +\end{alltt} +\end{definition} +where \meta{label} is a unique label that identifies this entry. +(Don't include the angle brackets \meta{ }. They just indicate the parts of +the code you need to change when you use this command in your document.) As +with similar labelling commands, such as \cs{label} or \cs{bibitem}, +the label should not contain active characters, so just use +\texttt{a}, \ldots, \texttt{z}, \texttt{A}, \ldots, \texttt{Z}, +\texttt{0}, \ldots, \texttt{9}. You may also be able to use some +punctuation characters, unless they have been made active (for +example, via \sty{babel}'s shorthand activation.) +The \meta{name} is the word, phrase or symbol you are defining, +and \meta{description} is the description. + +This command is a ``short'' command, which means that +\meta{description} can't contain a~paragraph break. If you have +a~long description, you can instead use: +\begin{definition} +\begin{alltt} +\cs{longnewglossaryentry}\marg{label} +\verb|{| + name=\marg{name}, + \meta{other options} +\verb|}| +\marg{description} +\end{alltt} +\end{definition} + +Examples: +\begin{enumerate} +\item Define the term ``set'' with the label \texttt{set}: \begin{verbatim} -\usepackage{glossaries} +\newglossaryentry{set} +{ + name={set}, + description={a collection of objects} +} \end{verbatim} -\begin{important} -Note that the \styfmt{glossaries} package must be loaded \emph{after} -the \sty{hyperref} package (contrary to the general advice that -\sty{hyperref} should be loaded last). The \sty{glossaries} package -should also be loaded after \sty{html}, \sty{inputenc}, -\sty{babel} and \sty{ngerman}. If you are using \sty{babel} I -recommend you use the \sty{glossaries} package option -\pkgopt[babel]{translate}: + +\item Define the symbol $\emptyset$ with the label +\texttt{emptyset}: \begin{verbatim} -\usepackage{babel} -\usepackage[translate=babel]{glossaries} +\newglossaryentry{emptyset} +{ + name={\ensuremath{\emptyset}}, + description={the empty set} +} \end{verbatim} -\end{important} -If you want to use \app{xindy} rather than \app{makeindex} to sort the -glossaries, you need to specify this in the package options: +\item Define the phrase ``Fish Age'' with the label +\texttt{fishage}: \begin{verbatim} -\usepackage[xindy]{glossaries} +\longnewglossaryentry{fishage} +{name={Fish Age}} +{% + A common name for the Devonian geologic period + spanning from the end of the Silurian Period to + the beginning of the Carboniferous Period. + + This age was known for its remarkable variety of + fish species. +} \end{verbatim} -Other package options are described in -\xrsectionref{sec:pkgopts}{glossaries-user}{Package Options} -in the main \sty{glossaries} user manual. +(The percent character discards the end of line character that would +otherwise cause an unwanted space to appear at the start of the +description.) -Next, you need to enable the creation of the various external -files that are required by the indexing application. This is done using: -\begin{definition} -\cs{makeglossaries} -\end{definition} - -\begin{important} -\emph{Don't} attempt to input any of these external files in your document. -\end{important} +\item Take care if the first letter is an extended Latin or +non-Latin character (either specified via a~command such as +\verb|\'e| or explicitly via the \sty{inputenc} package such +as \texttt{\'e}). This first letter must be placed in a~group: -\section{Defining a Term or Symbol} -\label{defterm} +\begin{verbatim} +\newglossaryentry{elite} +{ + name={{\'e}lite}, + description={select group or class} +} +\end{verbatim} +or +\begin{alltt} +\verb|\newglossaryentry{elite}| +\verb|{| + name=\verb|{{|\'e\verb|}lite}|, + description=\verb|{select group or class}| +\verb|}| +\end{alltt} +\end{enumerate} -You must define terms or symbols before you can use them in the -document. This is best done in the preamble. Each term is defined -using: +Acronyms or abbreviations can be defined using \begin{definition} -\cs{newglossaryentry}\marg{label}\marg{settings} +\cs{newacronym}\marg{label}\marg{short}\marg{long} \end{definition} -where \meta{label} is a unique label used to identify the term. -The second argument, \meta{settings}, is a key=value comma -separated list that is used to set the required information for -the term. A full list of available keys can be found in -\xrsectionref{sec:newglosentry}{glossaries-user}{Defining Glossary -Entries} -in the main \sty{glossaries} user manual. The principle keys are -\gloskey{name} and \gloskey{description}. - -For example, to define the term \qt{electrolyte}: -\begin{verbatim} -\newglossaryentry{electrolyte}{name=electrolyte, -description={solution able to conduct electric current}} -\end{verbatim} -In the above example, the label and the name happen to be the same. -In the next example, the name contains a ligature but the label -doesn't: -\begin{verbatim} -\newglossaryentry{oesophagus}{name=\oe sophagus, -description={canal from mouth to stomach}, -plural=\oe sophagi} -\end{verbatim} -In this case the label is \texttt{oesophagus}. Note that in this -case, the plural has to be specified using the \gloskey{plural} key -since it isn't formed by simply appending the letter \qt{s}. - -\begin{important} -If you want to define all your terms in a separate file \emph{don't} -use \ics{include} to input the file. You can use \ics{input} but -it's better to use \ics{loadglsentries}. (See -\xrsectionref{sec:loadglsentries}{glossaries-user}{Loading Entries -From a File}.) -\end{important} - -When you define terms, it is important to remember that they will -be sorted by an external application that doesn't interpret \LaTeX\ -commands. \app{xindy} is a little more \TeX-aware than \app{makeindex}, but -for this example they will both mis-sort \verb|\oe sophagus|. -Xindy will ignore the \verb*|\oe | part and will sort it according -to \texttt{sophagus}, so it will be placed with the terms starting -with an \qt{s}. \app{makeindex}, on the other hand, will sort it according -to \verb*|\oe sophagus| which starts with a symbol (the backslash), -so it will end up in the symbol group. You therefore need to -specify how to sort the term: -\begin{verbatim} -\newglossaryentry{oesophagus}{name=\oe sophagus, -description={canal from mouth to stomach}, -plural=\oe sophagi, -sort=oesophagus} -\end{verbatim} -Note, however, that if you use the \sty{inputenc} package and -\app{xindy}, you can use the encoded character \texttt{œ} rather than -\cs{oe} and \app{xindy} will sort it correctly: -\begin{verbatim} -\newglossaryentry{oesophagus}{name=œsophagus, -description={canal from mouth to stomach}, -plural=œsophagi} -\end{verbatim} - -If the name starts with an accented character, the first character -must be grouped: -\begin{verbatim} -\newglossaryentry{elite}{name={\'e}lite, -description={select group of people}, -sort=elite} +where \meta{label} is the label (as with the \cs{newglossaryentry} +and the \cs{longnewglossaryentry} commands), \meta{short} is the abbreviation or +acronym and \meta{long} is the long form. For example: +\begin{verbatim} +\newacronym{svm}{svm}{support vector machine} \end{verbatim} -or +This defines a glossary entry with the label \texttt{svm}. By +default, the \meta{name} is set to \meta{short} (``svm'' in the +above example) and the \meta{description} is set to \meta{long} +(``support vector machine'' in the above example). If, instead, you +want to be able to specify your own description you can do this +using the optional argument: +\begin{verbatim} +\newacronym + [description={statistical pattern recognition technique}] + {svm}{svm}{support vector machine} +\end{verbatim} + +There are other keys you can use when you define an entry. For +example, the \texttt{name} key used above indicates how the term +should appear in the list of entries (glossary). If the term should +appear differently when you reference it in the document, you need +to use the \texttt{text} key as well. + +For example: +\begin{verbatim} +\newglossaryentry{latinalph} +{ + name={Latin Alphabet}, + text={Latin alphabet}, + description={alphabet consisting of the letters + a, \ldots, z, A, \ldots, Z} +} +\end{verbatim} +This will appear in the text as \qt{Latin alphabet} but will be listed in +the glossary as \qt{Latin Alphabet}. + +Another commonly used key is \texttt{plural} for specifying the +plural of the term. This defaults to the value of the \texttt{text} +key with an ``s'' appended, but if this is incorrect, just use the +\texttt{plural} key to override it: \begin{verbatim} -\newglossaryentry{elite}{name={é}lite, -description={select group of people}} +\newglossaryentry{oesophagus} +{ + name={{\oe}sophagus}, + plural={{\oe}sophagi}, + description={canal from mouth to stomach} +} \end{verbatim} +(Remember from earlier that the initial ligature \cs{oe} needs to +be grouped.) -The name can also be a symbol, but you will also need to specify -the sort key. For example: +The plural forms for acronyms can be specified using the +\texttt{longplural} and \texttt{shortplural} keys. For example: \begin{verbatim} -\newglossaryentry{pi}{name={\ensuremath{\pi}}, -description={ratio of circumference of circle to its -diameter},sort=pi} +\newacronym + [longplural={diagonal matrices}] + {dm}{DM}{diagonal matrix} \end{verbatim} -It's also possible to have a name and a symbol. For example: +If omitted, the defaults are again obtained by appending an ``s'' to +the singular versions. + +It's also possible to have both a~name and a~corresponding symbol. +Just use the \texttt{name} key for the name and the \texttt{symbol} key +for the symbol. For example: \begin{verbatim} -\newglossaryentry{set}{name=set, -description={a collection of objects}, -symbol={\ensuremath{\mathcal{S}}}} +\newglossaryentry{emptyset} +{ + name={empty set}, + symbol={\ensuremath{\emptyset}}, + description={the set containing no elements} +} \end{verbatim} -Note, however, that not all glossary styles display the symbol -in the glossary. -\section{Using a Term} -\label{usingterm} +\section{Using Entries} +\label{sec:useterm} -Once you have defined a term, you can use it in the document. The -\sty{glossaries} package provides a number of commands that are -described in \xrsectionref{sec:glslink}{glossaries-user}{Links to -Glossary Entries} in the main \sty{glossaries} user manual. -Here, I shall just cover the main commands: +Once you have defined your entries, as described above, you can +reference them in your document. There are a~number of commands to +do this, but the most common one is: \begin{definition} \cs{gls}\marg{label} \end{definition} -This prints the term associated with \meta{label}. Using the -example in the previous section, \verb|\gls{oesophagus}| -will display \oe sophagus. If the \sty{hyperref} package has also -been loaded, the term will also be hyperlinked to the relevant -entry in the glossary. +where \meta{label} is the label you assigned to the entry when you +defined it. For example, \verb|\gls{fishage}| will display \qt{Fish +Age} in the text (given the definition from the previous section). + +If the entry was defined as an acronym (using \cs{newacronym} +described above), then \cs{gls} will display the full form the first +time it's used and just the short form on +subsequent use. For example, \verb|\gls{svm}| will display \qt{support vector +machine (svm)} the first time it's used, but the next occurrence of +\verb|\gls{svm}| will just display \qt{svm}. + +If you want the plural form, you can use: \begin{definition} \cs{glspl}\marg{label} \end{definition} -This prints the plural of the term associated with \meta{label}, -so \verb|\glspl{oesophagus}| will display \oe sophagi. Again, the -text will be a hyperlink to the relevant entry in the glossary, if -hyperlinks are defined. +instead of \cs{gls}\marg{label}. For example, \verb|\glspl{set}| +displays \qt{sets}. -There are also versions that convert the first character to upper -case if you need to start a sentence with a term: +If the term appears at the start of a~sentence, you can convert the +first letter to upper case using: \begin{definition} \cs{Gls}\marg{label} \end{definition} -and +for the singular form or \begin{definition} \cs{Glspl}\marg{label} \end{definition} -For example: +for the plural form. For example: \begin{verbatim} -\Glspl{electrolyte} usually exist as solutions of salts, -bases or acids. +\Glspl{set} are collections. \end{verbatim} +produces \qt{Sets are collections}. -Note that these commands all have two optional arguments that aren't -discussed here, but they are described in -\xrsectionref{sec:glslink}{glossaries-user}{Links to Glossary -Entries} in the main \sty{glossaries} user manual. - -\begin{important} -Don't use these commands in moving arguments, such -as those used by \cs{chapter}, \cs{section} and \cs{caption}. -\end{important} -You can, instead, use commands such as +If you've specified a symbol using the \texttt{symbol} key, you can +display it using: \begin{definition} -\cs{glsentrytext}\marg{label} +\cs{glssymbol}\marg{label} \end{definition} -See \xrsectionref{sec:glsnolink}{glossaries-user}{Using Glossary -Terms Without Links} in the main \sty{glossaries} user manual. \section{Acronyms} -\label{acronyms} +\label{sec:acronyms} + +Recall from above, the first time you use an acronym +with \cs{gls}, it's full form is displayed but subsequent uses +display only the short form. By default, the first use displays +\meta{long} (\meta{short}). That is, the long form is displayed +followed by the short form in parentheses. You can change this +first-use format with: +\begin{definition} +\cs{setacronymstyle}\marg{style name} +\end{definition} +(This must be used before you start defining your acronyms with +\cs{newacronym}.) There are a~number of predefined styles listed in +\xrsectionref{sec:predefinedacrstyles}{glossaries-user}{Predefined +Acronym Styles} in the main \sty{glossaries} user manual. Here are +a~few examples: +\begin{enumerate} +\item \meta{short} (\meta{long}) +\begin{verbatim} +\setacronymstyle{short-long} +\end{verbatim} +This displays the short form followed by the long form in +parentheses. -The \sty{glossaries} package also allows you to define acronyms. -By default, acronyms will be added to the main glossary, but if -you use the \pkgopt{acronym} package option, acronyms will be -placed in a separate list of acronyms: +\item \meta{long} (\cs{textsc}\marg{short}) +\begin{verbatim} +\setacronymstyle{long-short-sc} +\end{verbatim} +This is like the default style but the short form is displayed in +small caps. Remember that when you use \cs{textsc}\marg{text} to generate small +capitals, you must specify \meta{text} in lower case, so the short +form of the acronym should be defined in lower case. For example: \begin{verbatim} -\usepackage[acronym]{glossaries} +\newacronym{svm}{svm}{support vector machine} \end{verbatim} -Acronyms must be defined before use and are defined using: +\item \meta{long} (\cs{textsmaller}\marg{short}) +\begin{verbatim} +\setacronymstyle{long-short-sm} +\end{verbatim} +This is similar to the previous style but uses \cs{textsmaller} to +format the short form. Remember to load the \sty{relsize} package, +which defines \cs{textsmaller}, if you want to use this style. The +short form now needs to be defined in upper case: +\begin{verbatim} +\newacronym{svm}{SVM}{support vector machine} +\end{verbatim} + +\end{enumerate} + +\section{Displaying a List of Entries} +\label{sec:printglossaries} + +Suppose you now want to display a list of all the entries you've +referenced in your document. This is where things start to get +complicated and a~lot of new users get bewildered. You have three +options: + +\begin{description} +\item[]\optionlabel1: + + This is the simplest option but it's slow and if + you want a sorted list, it doesn't work for non-Latin alphabets. + + \begin{enumerate} + \item Add \cs{makenoidxglossaries} to your preamble (before you + start defining your entries, as described in + \sectionref{sec:defterm}). + + \item Put \begin{definition} -\cs{newacronym}\marg{label}\marg{abbrv}\marg{full} +\cs{printnoidxglossary}[sort=\meta{order},\meta{other options}] \end{definition} -where \meta{label} is the label identifying the acronym, \meta{abbrv} -is the abbreviated form and \meta{full} is the fully expanded text. -For example: + where you want your list of entries to appear. The sort + \meta{order} may be one of: \texttt{word} (word ordering), + \texttt{letter} (letter ordering), \texttt{case} (case-sensitive + letter ordering), \texttt{def} (in order of definition) or + \texttt{use} (in order of use). + + \item Run \LaTeX\ twice on your document. (As you would do to + make a~table of contents appear.) For example, click twice on + the ``typeset'' or ``build'' or ``PDF\LaTeX'' button in your editor. + \end{enumerate} + +\item[]\optionlabel2: + + This option uses an application called \texttt{makeindex} to sort + the entries. This application comes with all modern \TeX\ distributions, + but it's hard-coded for the non-extended Latin alphabet. This process + involves making \LaTeX\ write the glossary information to a temporary + file which \texttt{makeindex} reads. Then \texttt{makeindex} writes + a~new file containing the code to typeset the glossary. \LaTeX\ then + reads this file on the next run. + + \begin{enumerate} + \item Add \cs{makeglossaries} to your preamble (before you start + defining your entries). + + \item Put +\begin{definition} +\cs{printglossary}\oarg{options} +\end{definition} + where you want your list of entries (glossary) to appear. + + \item Run \LaTeX\ on your document. This creates files with the + extensions \texttt{.glo} and \texttt{.ist} (for example, if your + \LaTeX\ document is called \texttt{myDoc.tex}, then you'll have + two extra files called \texttt{myDoc.glo} and \texttt{myDoc.ist}). + If you look at your document at this point, you won't see the + glossary as it hasn't been created yet. + + \item Run \texttt{makeindex} with the \texttt{.glo} file as the + input file and the \texttt{.ist} file as the style so that + it creates an output file with the extension \texttt{.gls}. If + you have access to a terminal or a command prompt (for example, the + MSDOS command prompt for Windows users or the bash console for + Unix-like users) then you need to run the command: +\begin{verbatim} +makeindex -s myDoc.ist -o myDoc.gls myDoc.glo +\end{verbatim} + (Replace \texttt{myDoc} with the base name of your \LaTeX\ + document file. Avoid spaces in the file name.) If you don't know + how to use the command prompt, then you can probably access + \texttt{makeindex} via your text editor, but each editor has a + different method of doing this, so I~can't give a~general + description. You will have to check your editor's manual. + + The default sort is word order (``sea lion'' comes before ``seal''). + If you want letter ordering you need to add the \texttt{-l} + switch: +\begin{verbatim} +makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo +\end{verbatim} + + \item Once you have successfully completed the previous step, + you can now run \LaTeX\ on your document again. + \end{enumerate} + +\item[]\optionlabel3: + + This option uses an application called + \texttt{xindy} to sort the entries. This application is more + flexible than \texttt{makeindex} and is able to sort extended + Latin or non-Latin alphabets. It comes with \TeX~Live but not + with MiK\TeX. Since \texttt{xindy} is a Perl script, if you are + using MiK\TeX\ you will not only need to install \texttt{xindy}, you + will also need to install Perl. In a~similar way to \opt2, this + option involves making \LaTeX\ write the glossary information to + a~temporary file which \texttt{xindy} reads. Then \texttt{xindy} + writes a~new file containing the code to typeset the glossary. + \LaTeX\ then reads this file on the next run. + + \begin{enumerate} + \item Add the \texttt{xindy} option to the \sty{glossaries} +package option list: +\begin{verbatim} +\usepackage[xindy]{glossaries} +\end{verbatim} + + \item Add \cs{makeglossaries} to your preamble (before you start + defining your entries). + + \item Put +\begin{definition} +\cs{printglossary}\oarg{options} +\end{definition} + where you want your list of entries (glossary) to appear. + + \item Run \LaTeX\ on your document. This creates files with the + extensions \texttt{.glo} and \texttt{.xdy} (for example, if your + \LaTeX\ document is called \texttt{myDoc.tex}, then you'll have + two extra files called \texttt{myDoc.glo} and \texttt{myDoc.xdy}). + If you look at your document at this point, you won't see the + glossary as it hasn't been created yet. + + \item Run \texttt{xindy} with the \texttt{.glo} file as the + input file and the \texttt{.xdy} file as a~module so that + it creates an output file with the extension \texttt{.gls}. You + also need to set the language name and input encoding. If + you have access to a terminal or a command prompt (for example, the + MSDOS command prompt for Windows users or the bash console for + Unix-like users) then you need to run the command (all on one + line): +\begin{verbatim} +xindy -L english -C utf8 -I xindy -M myDoc +-t myDoc.glg -o myDoc.gls myDoc.glo +\end{verbatim} + (Replace \texttt{myDoc} with the base name of your \LaTeX\ + document file. Avoid spaces in the file name. If necessary, also replace + \texttt{english} with the name of your language and \texttt{utf8} + with your input encoding.) If you don't know + how to use the command prompt, then you can probably access + \texttt{xindy} via your text editor, but each editor has a + different method of doing this, so I~can't give a~general + description. You will have to check your editor's manual. + + The default sort is word order (``sea lion'' comes before ``seal''). + If you want letter ordering you need to add the + \texttt{order=letter} package option: +\begin{verbatim} +\usepackage[xindy,order=letter]{glossaries} +\end{verbatim} + + \item Once you have successfully completed the previous step, + you can now run \LaTeX\ on your document again. + + \end{enumerate} + +\end{description} + +For \optsand23, it can be difficult to remember all the +parameters required for \texttt{makeindex} or \texttt{xindy}, so the +\sty{glossaries} package provides a~script called +\texttt{makeglossaries} that reads the \texttt{.aux} file to +determine what settings you have used and will then run +\texttt{makeindex} or \texttt{xindy}. Again, this is a~command line +application and can be run in a~terminal or command prompt. For +example, if your \LaTeX\ document is in the file \texttt{myDoc.tex}, +then run: +\begin{verbatim} +makeglossaries myDoc +\end{verbatim} +(Replace \texttt{myDoc} with the base name of your \LaTeX\ document +file. Avoid spaces in the file name.) If you don't know how to use +the command prompt, you can probably access \texttt{makeglossaries} +via your text editor. Check your editor's manual for advice. If you +are using \texttt{arara} then you can just use the directives: +\begin{verbatim} +% arara: pdflatex +% arara: makeglossaries +% arara: pdflatex +\end{verbatim} + +The \texttt{makeglossaries} script is written in Perl, so you need +a~Perl interpreter installed. If you are using a~Unix-like operating +system then you most likely have one installed. If you are using +Windows with the \TeX~Live distribution, then you can use the Perl +interpreter that comes with \TeX~Live. If you are using Windows and +MiK\TeX\ then you need to install a~Perl distribution for Windows. +If you are using \opt3, then you need to do this anyway as +\texttt{xindy} is also written in Perl. If you are using \opt2 +and can't work out how to install Perl (or for some reason don't +want to install it) then just use \texttt{makeindex} directly, as +described above. + +When sorting the entries, the string comparisons are made according +to each entry's \texttt{sort} key. If this is omitted, the +\texttt{name} key is used. For example, recall the earlier +definition: +\begin{verbatim} +\newglossaryentry{elite} +{ + name={{\'e}lite}, + description={select group or class} +} +\end{verbatim} +No \texttt{sort} key was used, so it's set to the same as the +\texttt{name} key: \verb|{\'e}lite|. How this is interpreted depends +on which option you have used: +\begin{description} +\item[\opt1:] By default, the accent command will be stripped so the +sort value will be \texttt{elite}. This will put the entry in the +\qt{E} letter group. If you use the +\pkgopt[true]{sanitizesort} package option, the sort value will be +interpreted as the sequence of characters: \verb|\| \texttt{'} \texttt{e} +\texttt{l} \texttt{i} \texttt{t} and \texttt{e}. This will place +this entry before the \qt{A} letter group since it starts with a symbol. + +\item[\opt2:] The sort key will be interpreted the sequence of characters: +\verb|{| \verb|\| \verb|'| \texttt{e} \verb|}| \texttt{l} \texttt{i} \texttt{t} +and \texttt{e}. The first character is an opening curly brace +\verb|{| so \texttt{makeindex} will put this entry in the ``symbols'' group. + +\item[\opt3:] +\texttt{xindy} disregards \LaTeX\ commands so it sorts on +\texttt{elite}, which puts this entry in the \qt{E} group. +\end{description} + + +If the \sty{inputenc} package is used and the entry is defined as: +\begin{alltt} +\verb|\newglossaryentry{elite}| +\verb|{| + name=\verb|{{|\'e\verb|}lite},| + description=\verb|{select group or class}| +\verb|}| +\end{alltt} +then: +\begin{description} +\item[\opt1:] By default the sort value will be interpreted as +\texttt{elite} so the entry will be put in the \qt{E} letter group. +If you use the \pkgopt[true]{sanitizesort} package option, the +sort value will be interpreted as \texttt{\'elite} where \'e has +been sanitized (so it's no longer an active character) which will +put this entry before the \qt{A} letter group. + +\item[\opt2:] \texttt{makeindex} doesn't recognise \texttt{\'e} as +a~letter so it will be put in the symbols group. + +\item[\opt3:] \texttt{xindy} will correctly recognise the sort value +\texttt{\'elite} and will place it in whatever letter group is +appropriate for the given language setting. (In English, this would +just be the \qt{E} letter group.) +\end{description} + +Therefore if you have extended Latin or non-Latin characters, your +best option is to use \texttt{xindy} (\opt3) with the \sty{inputenc} +package. If you use \texttt{makeindex} (\opt2) you need to specify the +\texttt{sort} key like this: \begin{verbatim} -\newacronym{label}{svm}{support vector machine} -\end{verbatim} - -Once the acronym is defined, it can be used in the same way as -any other glossary term with commands such as \cs{gls} and -\cs{glspl}. On first use, the default will display \meta{full} -(\meta{abbrv}). On subsequent use, only the abbreviation will -appear. For example: -\begin{verbatim} -A \gls{svm} was implemented. -\end{verbatim} -If this is the first time this term has been used, the above would -produce: -\begin{display} -A support vector machine (svm) was implemented. -\end{display} -otherwise it would produce: -\begin{display} -A svm was implemented. -\end{display} -If you prefer a different way of displaying the acronyms (for -example, putting the long form in a footnote on first use) it's -possible to change the acronym style. For further -details, see \xrsectionref{sec:acronyms}{glossaries-user}{Acronyms} -in the main \sty{glossaries} user manual. - -You can reset an acronym so that the next use fully -expands it again using: +\newglossaryentry{elite} +{ + name={{\'e}lite}, + sort={elite}, + description={select group or class} +} +\end{verbatim} +If you use \opt1, you may or may not need to use the \texttt{sort} +key, but you will need to be careful about fragile commands in the +\texttt{name} key if you don't set the \texttt{sort} key. + +\Tableref{tab:optionsp+c} summarises the pros and cons of three options described +above. + +\begin{table}[htbp] + \caption{Glossary Options: Pros and Cons} + \label{tab:optionsp+c} + {% + \centering + \begin{tabular}{>{\raggedright}p{0.3\textwidth}ccc} + & \bfseries \opt1 & \bfseries \opt2 & \bfseries \opt3\\ + Requires an external application? & + \no & \yes & \yes\\ + Requires Perl? & + \no & \no & \yes\\ + Can sort extended Latin + or non-Latin alphabets? & + \no\textsuperscript{\textdagger} & \no & \yes\\ + Efficient sort algorithm? & + \no & \yes & \yes\\ + Can form ranges in the location lists? & + \no & \yes & \yes\\ + Can have non-standard locations? & + \yes & \no & \yes\\ + \ics{newglossaryentry} restricted to preamble? & + \yes & \no & \no + \end{tabular} + \par + }\textsuperscript{\textdagger} Strips standard \LaTeX\ accents so, +for example, \verb|\AA| is treated the same as A. +\end{table} + +\section{Customising the Glossary} +\label{sec:glosstyle} + +The default glossary style uses the \texttt{description} environment +to display the entry list. Each entry name is set in the optional +argument of \cs{item} which means that it will typically be +displayed in bold. You can switch to medium weight by redefining +\cs{glsnamefont}: +\begin{verbatim} +\renewcommand*{\glsnamefont}[1]{\textmd{#1}} +\end{verbatim} + +By default, a~full stop is appended to the description. To prevent +this from happening use the \texttt{nopostdot} package option: +\begin{verbatim} +\usepackage[nopostdot]{glossaries} +\end{verbatim} + +By default, a~location list is displayed for each entry. This refers +to the document locations (for example, the page number) where the +entry has been referenced. If you use \optsor23 described +in \sectionref{sec:printglossaries} location ranges will be compressed. For +example, if an entry was used on pages~1, 2 and~3, with +\optsor23 the location list will appear as 1--3, but with \opt1 it +will appear as 1, 2, 3. If you don't want the locations displayed +you can hide them using the \texttt{nonumberlist} package option: +\begin{verbatim} +\usepackage[nonumberlist]{glossaries} +\end{verbatim} + +Entries are grouped according to the first letter of +each entry's \texttt{sort} key. By default a~vertical gap is placed +between letter groups. You can suppress this with the +\texttt{nogroupskip} package option: +\begin{verbatim} +\usepackage[nogroupskip]{glossaries} +\end{verbatim} + +If the default style doesn't suit your document, you can change the +style using: \begin{definition} -\cs{glsreset}\marg{label} +\cs{setglossarystyle}\marg{style name} \end{definition} -or you can reset all acronyms using +There are a~number of predefined styles. Glossaries can vary from +a~list of symbols with a~terse description to a~list of words or +phrases with descriptions that span multiple paragraphs, so there's +no ``one style fits all'' solution. You need to choose a~style that +suits your document. + +Examples: +\begin{enumerate} + \item You have entries where the name is a~symbol and the + description is a~brief phrase or short sentence. Try one of the + ``mcol'' styles defined in the \sty{glossary-mcols} package. For example: +\begin{verbatim} +\usepackage[nogroupskip,nopostdot]{glossaries} +\usepackage{glossary-mcols} +\setglossarystyle{mcolindex} +\end{verbatim} + + \item You have entries where the name is a~word or phrase and the +description spans multiple paragraphs. Try one of the ``altlist'' styles. For +example: +\begin{verbatim} +\usepackage[nopostdot]{glossaries} +\setglossarystyle{altlist} +\end{verbatim} + + \item You have entries where the name is a~single word, the + description is brief, and an associated symbol has been set. + Use one of the styles that display the symbol (not all of them do). + For example, one of the tabular styles: +\begin{verbatim} +\usepackage[nopostdot,nonumberlist]{glossaries} +\setglossarystyle{long4col} +\end{verbatim} +or one of the ``tree'' styles: +\begin{verbatim} +\usepackage[nopostdot,nonumberlist]{glossaries} +\setglossarystyle{tree} +\end{verbatim} +\end{enumerate} + +If your glossary consists of a~list of acronyms and you also want to +specify a~description as well as the long form, then you need to use +an acronym style that will suit the glossary style. For example, +use the \texttt{long-short-desc} acronym style: +\begin{verbatim} +\setacronymstyle{long-short-desc} +\end{verbatim} +Define the acronyms with a~description: +\begin{verbatim} +\newacronym + [description={statistical pattern recognition technique}] + {svm}{svm}{support vector machine} +\end{verbatim} +Choose a~glossary style that suits wide entry names: +\begin{verbatim} +\setglossarystyle{altlist} +\end{verbatim} + +\section{Multiple Glossaries} +\label{sec:multigloss} + +The \sty{glossaries} package predefines a~default \texttt{main} +glossary. When you define an entry (using one of the commands +described in \sectionref{sec:defterm}), that entry is automatically +assigned to the default glossary, unless you indicate otherwise +using the \texttt{type} key. However you first need to +make sure the desired glossary has been defined. This is done using: \begin{definition} -\cs{glsresetall} +\cs{newglossary}\oarg{glg}\marg{label}\marg{gls}\marg{glo}\marg{title} \end{definition} -For further details on resetting and unsetting acronyms, see -\xrsectionref{sec:glsunset}{glossaries-user}{Unsetting and -Resetting Entry Flags} -in the main \sty{glossaries} user manual. +The \meta{label} is a~label that uniquely identifies this new +glossary. As with other types of identifying labels, be careful not +to use active characters in \meta{label}. The final argument +\meta{title} is the section or chapter heading used by +\cs{printglossary} or \cs{printnoidxglossary}. The other arguments +indicate the file extensions used by +\texttt{makeindex}\slash\texttt{xindy} (described in +\sectionref{sec:printglossaries}). If you use \opt1 described +above, the \meta{glg}, \meta{gls} and \meta{glo} arguments are +ignored. In the case of \optsor23, all glossary definitions must come before +\cs{makeglossaries}. + +Since it's quite common for documents to have both a~list of terms +and a~list of acronyms, the \sty{glossaries} package provides the +package option \texttt{acronyms}, which is a~convenient shortcut for +\begin{verbatim} +\newglossary[alg]{acronym}{acr}{acn}{\acronymname} +\end{verbatim} +It also changes the behaviour of \cs{newacronym} so that acronyms +are automatically put in the list of acronyms instead of the main +glossary. -\section{Displaying the Glossary or List of Acronyms} -\label{printglossaries} +For example, suppose you want a~main glossary for terms, a~list of +acronyms and a~list of notation: +\begin{verbatim} +\usepackage[acronyms]{glossaries} +\newglossary[nlg]{notation}{not}{ntn}{Notation} +\end{verbatim} +After \cs{makeglossaries} (or \cs{makenoidxglossaries}) you can +define the entries. For example: +\begin{verbatim} +\newglossaryentry{gls:set} +{% This entry goes in the `main' glossary + name=set, + description={A collection of distinct objects} +} + +% This entry goes in the `acronym' glossary: +\newacronym{svm}{svm}{support vector machine} + +\newglossaryentry{not:set} +{% This entry goes in the `notation' glossary: + type=notation, + name={\ensuremath{\mathcal{S}}}, + description={A set}, + sort={S}} +\end{verbatim} +or if you don't like using \cs{ensuremath}: +\begin{verbatim} +\newglossaryentry{not:set} +{% This entry goes in the `notation' glossary: + type=notation, + name={$\mathcal{S}$}, + text={\mathcal{S}}, + description={A set}, + sort={S}} +\end{verbatim} -In order to display the sorted list of terms, you first need to -use +Each glossary is displayed using: +\begin{definition} +\cs{printnoidxglossary}[type=\meta{type}] +\end{definition} +(\opt1) or +\begin{definition} +\cs{printglossary}[type=\meta{type}] +\end{definition} +(\optsand23). Where \meta{type} is the glossary label. If the +type is omitted the default \texttt{main} glossary is assumed. + +There's a~convenient shortcut that will display all the defined +glossaries: +\begin{definition} +\cs{printnoidxglossaries} +\end{definition} +(\opt1) or \begin{definition} \cs{printglossaries} \end{definition} -at the place where you want the glossary and list of acronyms to -appear. Note that \cs{printglossaries} won't produce any text the -first time you create your document, as an external indexing -application needs to be used to sort and collate the entries. -Creating the completed document is therefore \emph{at least} a three -step process. - -Suppose your document is called \texttt{myDoc.tex}, then you need -to: -\begin{enumerate} -\item Build/\LaTeX\ your document, either by clicking on an -appropriate button in your front-end/text editor or by typing the -following at a terminal/command prompt: +(\optsand23). + +If you use \opt1, you don't need to do anything else. If you use +\optsor23 with the \texttt{makeglossaries} Perl script, you +similarly don't need to do anything else. If you use \optsor23 +without the \texttt{makeglossaries} Perl script then you need to +make sure you run \texttt{makeindex}\slash\texttt{xindy} \emph{for +each defined glossary}. The \meta{gls} and \meta{glo} arguments of +\cs{newglossary} specify the file extensions to use instead of +\texttt{.gls} and \texttt{.glo}. The optional argument \meta{glg} is +the file extension for the transcript file. This should be different +for each glossary in case you need to check for +\texttt{makeindex}\slash\texttt{xindy} errors or warnings if things +go wrong. + +For example, suppose you have three glossaries in your document +(\texttt{main}, \texttt{acronym} and \texttt{notation}), +specified using: \begin{verbatim} -latex myDoc +\usepackage[acronyms]{glossaries} +\newglossary[nlg]{notation}{not}{ntn}{Notation} \end{verbatim} +Then (assuming your \LaTeX\ document is in a~file called +\texttt{myDoc.tex}): + +\begin{description} +\item\opt2: -\item Run the indexing application on the external file(s) created -by the \sty{glossaries} package. If you have used the \pkgopt{xindy} -package option, you must use \app{xindy}, otherwise you must use -\app{makeindex}. The \sty{glossaries} package comes with a convenient -Perl wrapper that calls the appropriate indexing application the -required number of times with the required options. If you have Perl -installed, all you need to do is type +You need to run \texttt{makeindex} three times: \begin{verbatim} -makeglossaries myDoc +makeindex -t myDoc.glg -s myDoc.ist -o myDoc.gls myDoc.glo +makeindex -t myDoc.alg -s myDoc.ist -o myDoc.acr myDoc.acn +makeindex -t myDoc.nlg -s myDoc.ist -o myDoc.not myDoc.ntn \end{verbatim} -in a terminal or command prompt. If you are using a front-end (such -as WinEdt or TeXnicCenter) and you want it to automatically run -makeglossaries when you build your document, you will need to -consult the front-end's documentation. -If you don't have Perl installed, you will need to call -\app{makeindex} or \app{xindy} explicitly. This is more complicated -and is described in -\xrsectionref{sec:makeglossaries}{glossaries-user}{Generating the -Associated Glossary Files} in the main \sty{glossaries} user manual. +\item\opt3:\nopagebreak -\item Once you have successfully run the indexing application, you -need to build/\LaTeX\ your document again (see step~1). -\end{enumerate} -Note that sometimes you may have to repeat steps~2 and~3. - -The appearance of the glossary depends on the glossary style in -use. The default style uses the \env{description} environment, -but there are many other styles available. These are described -in \xrsectionref{sec:styles}{glossaries-user}{Glossary Styles} -in the main \sty{glossaries} user manual. -By default, a number or list of numbers will appear after each entry -in the glossary. This indicates the page (or pages) -on which the term was used. This list can be suppressed using -the \pkgopt{nonumberlist} package option: +You need to run \texttt{xindy} three times (be careful not to insert +line breaks where the line has wrapped.) \begin{verbatim} -\usepackage[nonumberlist]{glossaries} +xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg +-o myDoc.gls myDoc.glo +xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.alg +-o myDoc.acr myDoc.acn +xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.nlg +-o myDoc.not myDoc.ntn +\end{verbatim} +\end{description} + +\section[glossaries and hyperref]{\styfmt{glossaries} and \styfmt{hyperref}} +\label{sec:hyperref} + +Take care if you use the \sty{glossaries} package with +\sty{hyperref}. Contrary to the usual advice that \sty{hyperref} +should be loaded last, \sty{glossaries} must be loaded \emph{after} +\sty{hyperref}: +\begin{verbatim} +\usepackage[colorlinks]{hyperref} +\usepackage{glossaries} \end{verbatim} +If you use \sty{hyperref} make sure you use PDF\LaTeX\ rather than +the \LaTeX\ to DVI engine. The DVI format can't break hyperlinks across +a~line so long glossary entries (such as the full form of acronyms) +won't line wrap with the DVI engine. Also, hyperlinks in sub- or +superscripts aren't correctly sized with the DVI format. + +By default, if the \sty{hyperref} package has been loaded, commands +like \cs{gls} will form a~hyperlink to the relevant entry in the +glossary. If you don't want this to happen for \emph{all} your +glossaries, then use +\begin{definition} +\cs{glsdisablehyper} +\end{definition} +If you want hyperlinks suppressed for entries in specific +glossaries, then use the \texttt{nohypertypes} package option. For +example, if you don't want hyperlinks for entries in the \texttt{acronym} and +\texttt{notation} glossaries but you do want them for entries in the +\texttt{main} glossary, then do: +\begin{verbatim} +\usepackage[colorlinks]{hyperref} +\usepackage[acronym,nohypertypes={acronym,notation}]{glossaries} +\newglossary[nlg]{notation}{not}{ntn}{Notation} +\end{verbatim} + +If you want the hyperlinks suppressed the first time an entry is +used, but you want hyperlinks for subsequence references then use +the \texttt{hyperfirst=false} package option: +\begin{verbatim} +\usepackage[colorlinks]{hyperref} +\usepackage[hyperfirst=false]{glossaries} +\end{verbatim} + +Take care not to use non-expandable commands in PDF bookmarks. This +isn't specific to the \sty{glossaries} package but is a~limitation +of PDF bookmarks. Non-expandable commands include commands like +\cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl}. The \sty{hyperref} +package provides a~way of specifying alternative text for the PDF +bookmarks via \cs{texorpdfstring}. For example: +\begin{verbatim} +\section{The \texorpdfstring{\gls{fishage}}{Fish Age}} +\end{verbatim} +However, it's not a~good idea to use commands like \cs{gls} in +a~section heading as you'll end up with the table of contents in +your location list. Instead you can use +\begin{definition} +\cs{glsentrytext}\marg{label} +\end{definition} +This is expandable provided that the \texttt{text} key doesn't +containing non-expandable code. For example, the following works: +\begin{verbatim} +\section{The \glsentrytext{fishage}} +\end{verbatim} +and it doesn't put the table of contents in the location list. + +\section{Cross-References} +\label{sec:xr} + +You can add a~reference to another entry in a~location list using +the \texttt{see=}\marg{label} key when you define an entry. +The referenced entry must also be defined. + +For example: +\begin{verbatim} +\longnewglossaryentry{devonian}{name={Devonian}}% +{% + The geologic period spanning from the end of the + Silurian Period to the beginning of the Carboniferous Period. + + This age was known for its remarkable variety of + fish species. +} + +\newglossaryentry{fishage} +{ + name={Fish Age}, + description={Common name for the Devonian period}, + see={devonian} +} +\end{verbatim} +The cross-reference will appear as \qt{\emph{see} Devonian}. You can +change the \qt{see} tag using the format +\texttt{see=}\oarg{tag}\meta{label}. For example: +\begin{verbatim} +\newglossaryentry{latinalph} +{ + name={Latin alphabet}, + description={alphabet consisting of the letters + a, \ldots, z, A, \ldots, Z}, + see=[see also]{exlatinalph} +} +\newglossaryentry{exlatinalph} +{ + name={extended Latin alphabet}, + description={The Latin alphabet extended to include + other letters such as ligatures or diacritics.} +} +\end{verbatim} +If you use the \texttt{see} key in the optional argument of +\cs{newacronym}, make sure you enclose the value in braces. For +example: +\begin{verbatim} +\newacronym{ksvm}{ksvm}{kernel support vector machine} +\newacronym + [see={[see also]{ksvm}}] + {svm}{svm}{support vector machine} +\end{verbatim} + +\section{Further Information} +\label{sec:moreinfo} Further information can be found in the main \sty{glossaries} \docref{user manual}{glossaries-user} and there is also an \href{http://www.latex-community.org/index.php?option=com_content&view=article&id=263:glossaries-nomenclature-lists-of-symbols-and-acronyms&catid=55:latex-general&Itemid=114}{article on the glossaries package} on the \urlfootref{http://www.latex-community.org/}{\LaTeX\ Community's} -Know How section. +Know How section and a~chapter on the \sty{glossaries} package in +\href{http://www.dickimaw-books.com/latex/thesis/}{Using +\LaTeX\ to Write a PhD Thesis}. \end{document} |