summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex1192
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}