diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/glossaries/glossaries-user.tex |
Initial commit
Diffstat (limited to 'macros/latex/contrib/glossaries/glossaries-user.tex')
-rw-r--r-- | macros/latex/contrib/glossaries/glossaries-user.tex | 13059 |
1 files changed, 13059 insertions, 0 deletions
diff --git a/macros/latex/contrib/glossaries/glossaries-user.tex b/macros/latex/contrib/glossaries/glossaries-user.tex new file mode 100644 index 0000000000..698933ac27 --- /dev/null +++ b/macros/latex/contrib/glossaries/glossaries-user.tex @@ -0,0 +1,13059 @@ +\documentclass[report,inlinetitle,widecs]{nlctdoc} + +\usepackage[inner=0.5in,includemp]{geometry} + +\usepackage{array} +\usepackage{alltt} +\usepackage{pifont} +\usepackage{textcomp} +\usepackage{amssymb} +\ifpdf + \usepackage{lmodern} + \usepackage{mathpazo} + \usepackage[scaled=.88]{helvet} + \usepackage{courier} + \usepackage{metalogo} +\else + \newcommand{\grimace}{{\fontencoding {U}\fontfamily{futs}\selectfont \char77}} + \providecommand{\XeLaTeX}{XeLaTeX} + \providecommand{\XeTeX}{XeTeX} +\fi +\usepackage[colorlinks, + bookmarks, + linkcolor=blue, + hyperindex=false, + pdfauthor={Nicola L.C. Talbot}, + pdftitle={User Manual for glossaries.sty}, + pdfkeywords={LaTeX,package,glossary,acronyms}]{hyperref} +\usepackage{xr-hyper} +\usepackage[ + xindy, + nonumberlist, + toc, + nopostdot, + nogroupskip, + style=altlist +]{glossaries} +\usepackage{glossary-inline} + +\pagestyle{headings} + +\glsnoexpandfields + +\renewcommand*{\glsseeformat}[3][\seename]{% + (\xmakefirstuc{#1} \glsseelist{#2}.)% +} + +\renewcommand*{\glossarypreamble}{% +\emph{This glossary style was setup using:} +\begin{ttfamily} +\begin{tabbing} +\cs{usepackage}[\=xindy,\\ +\+\>nonumberlist,\\ + toc,\\ + nopostdot,\\ + style=altlist,\\ + nogroupskip]\{glossaries\} +\end{tabbing} +\end{ttfamily} +} + +\ifpdf +\else + % Need an extra line break in the html version + % (Don't have time to fiddle with cfg files!) + \renewcommand*{\glossentry}[2]{% + \item[\glsentryitem{#1}\glstarget{#1}{\glossentryname{#1}}]\mbox{}\newline + \glossentrydesc{#1}\glspostdescription\space #2\newline}% +\fi + +\makeglossaries + +\renewcommand*{\main}[1]{\hyperpage{#1}} +\newcommand*{\htextbf}[1]{\textbf{\hyperpage{#1}}} +\newcommand*{\itermdef}[1]{\index{#1|htextbf}} + +\newcommand{\itempar}[1]{\item[{#1}]\mbox{}\par} + +\newcommand{\pkgoptdef}[1]{\hypertarget{pkgopt:#1}{\pkgopt{#1}}} + +\newcommand{\glslike}{\hyperref[sec:gls-like]{\cs{gls}-like}} +\newcommand{\glstextlike}{\hyperref[sec:glstext-like]{\cs{glstext}-like}} + +\IndexPrologue{\chapter*{\indexname} + \addcontentsline{toc}{chapter}{\indexname}% + \markboth{\indexname}{\indexname}} + +\longnewglossaryentry{indexingapp}% +{ + name={Indexing application}, + text={indexing application} +}% +{% + An application (piece of software) separate from + \TeX/\LaTeX\ that collates and sorts information that has an + associated page reference. Generally the information is an index + entry but in this case the information is a glossary entry. + There are two main indexing applications that are used with \TeX: + \gls{makeindex} and \gls{xindy}. These are both + \gls{cli} applications. +} + +\longnewglossaryentry{cli} +{ + name={Command Line Interface (CLI)}, + first={command line interface (CLI)}, + text={CLI} +} +{% + An application that doesn't have a graphical user + interface. That is, an application that doesn't have any windows, + buttons or menus and can be run in + \href{http://www.dickimaw-books.com/latex/novices/html/terminal.html}{a command + prompt or terminal}. +} + +\longnewglossaryentry{xindy}{% + name={\appfmt{xindy}\index{xindy=\appfmt{xindy}|htextbf}}, + sort={xindy}, + text={\appfmt{xindy}\iapp{xindy}} +}% +{% + A flexible \gls{indexingapp} with multilingual + support written in Perl. +} + +\newglossaryentry{makeindex}{% +name={\appfmt{makeindex}\index{makeindex=\appfmt{makeindex}|htextbf}},% +sort={makeindex},% +text={\appfmt{makeindex}\iapp{makeindex}},% +description={An \gls{indexingapp}.} +} + +\newglossaryentry{bib2gls}{% +name={\appfmt{bib2gls}\index{bib2gls=\appfmt{bib2gls}|htextbf}},% +sort={bib2gls},% +text={\appfmt{bib2gls}\iapp{bib2gls}},% +description={An \gls{indexingapp} that combines two functions in +one: (1) fetches entry definition from a \texttt{.bib} file +based on information provided in the \texttt{.aux} file (similar +to \appfmt{bibtex}); (2) hierarchically sorts and collates location +lists (similar to \appfmt{makeindex} and \appfmt{xindy}). +This application is designed for use with \styfmt{glossaries-extra} +and can't be used with just the base \styfmt{glossaries} package.} +} + +\newglossaryentry{makeglossaries}{% +name={\appfmt{makeglossaries}\index{makeglossaries=\appfmt{makeglossaries}|htextbf}},% +sort={makeglossaries},% +text={\appfmt{makeglossaries}\iapp{makeglossaries}},% +description={A custom designed Perl script interface +to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries} +package. \TeX\ distributions on Windows convert the original +\texttt{makeglossaries} script into an executable +\texttt{makeglossaries.exe} for convenience (but Perl is still +required).} +} + +\newglossaryentry{makeglossaries-lite.lua}{% +name={\appfmt{makeglossaries-lite}\index{makeglossaries-lite=\appfmt{makeglossaries-lite}|htextbf}},% +sort={makeglossaries-lite},% +text={\appfmt{makeglossaries-lite}\iapp{makeglossaries-lite}},% +description={A custom designed Lua script interface +to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries} +package. This is a cut-down alternative to the Perl +\appfmt{makeglossaries} script. If you have Perl installed, use the +Perl script instead. This script is actually distributed with the +file name \texttt{makeglossaries-lite.lua}, but \TeX~Live +(on Unix-like systems) creates a symbolic link +called \texttt{makeglossaries-lite} (without the \texttt{.lua} +extension) to the actual \texttt{makeglossaries-lite.lua} script.} +} + +\longnewglossaryentry{makeglossariesgui}{% +name={\appfmt{makeglossariesgui}\index{makeglossariesgui=\appfmt{makeglossariesgui}|htextbf}},% +sort={makeglossariesgui},% +text={\appfmt{makeglossariesgui}\iapp{makeglossariesgui}}% +}% +{% + A Java GUI alternative to \gls{makeglossaries} that + also provides diagnostic tools. Available separately on + \href{http://ctan.org/pkg/makeglossariesgui}{CTAN}. +} + +\newglossaryentry{numberlist}{% +name={Number list\itermdef{number list}},% +sort={number list},% +text={number list\iterm{number list}},% +description={A list of \glslink{entrylocation}{entry locations} (also +called a location list). The number list can be suppressed using the +\pkgopt{nonumberlist} package option.} +} + +\newglossaryentry{entrylocation}{% +name={Entry location\itermdef{entry location}},% +sort={entry location},% +text={entry location\iterm{entry location}},% +description={The location of the entry in the document. This +defaults to the page number on which the entry appears. An entry may +have multiple locations.} +} + +\newglossaryentry{locationlist}{% +name={Location list},% +text={location list}, +sort={location list},% +description={A list of \glslink{entrylocation}{entry locations}. +See \gls{numberlist}.}% +} + +\newglossaryentry{linktext}{% +name={Link text\itermdef{link text}}, +sort={link text},% +text={link text\iterm{link text}}, +description={The text produced by commands such as \ics{gls}. It may +or may not be a hyperlink to the glossary.} +} + +\let\glsd\glsuseri +\let\glsation\glsuserii + +\longnewglossaryentry{firstuse}{% +name={First use\ifirstuse}, +sort={first use},% +text={first use},% +user1={first used}} +{% + The first time a glossary entry is used (from the start of the + document or after a reset) with one of the + following commands: \ics{gls}, \ics{Gls}, \ics{GLS}, \ics{glspl}, + \ics{Glspl}, \ics{GLSpl} or \ics{glsdisp}. + \glsseeformat{firstuseflag,firstusetext}{} +} + +\longnewglossaryentry{firstuseflag}{% +name={First use flag\ifirstuseflag}, +sort={first use flag},% +text={first use flag}% +} +{% + A conditional that determines whether or not the entry + has been used according to the rules of \gls{firstuse}. Commands + to unset or reset this conditional are described in + \sectionref{sec:glsunset}. +} + +\newglossaryentry{firstusetext}{% +name={First use text\ifirstusetext}, +sort={first use text},% +text={first use text},% +description={The text that is displayed on \gls{firstuse}, which is +governed by the \gloskey{first} and \gloskey{firstplural} keys of +\ics{newglossaryentry}. (May be overridden by +\ics{glsdisp} or by \ics{defglsentry}.)}% +} + +\longnewglossaryentry{sanitize}{% +name={Sanitize\itermdef{sanitize}},% +sort={sanitize}, +text={sanitize\iterm{sanitize}},% +user1={sanitized\protect\iterm{sanitize}},% +user2={sanitization\protect\iterm{sanitize}}% +}% +{% + Converts command names into character sequences. That is, a command called, + say, \cs{foo}, is converted into the sequence of characters: + \cs{}, \texttt{f}, \texttt{o}, \texttt{o}. Depending on the font, + the backslash character may appear as a dash when used in the + main document text, so \cs{foo} will appear as: ---foo. + + Earlier versions of \styfmt{glossaries} used this technique to write + information to the files used by the indexing applications to + prevent problems caused by fragile commands. Now, this is only used + for the \gloskey{sort} key. +} + +\newglossaryentry{latinchar}{% + name={Latin Character\itermdef{Latin character}}, + text={Latin character\iterm{Latin character}}, + sort={Latin character}, + description={One of the letters \texttt{a}, \ldots, \texttt{z}, + \texttt{A}, \ldots, \texttt{Z}\@. + See also \gls{exlatinchar}.} +} + +\newglossaryentry{exlatinchar}{% + name={Extended Latin Character\itermdef{extended Latin character}}, + text={extended Latin character\iterm{extended Latin character}}, + sort={extended Latin character}, + description={A character that's created by combining \glspl{latinchar} + to form ligatures (e.g.\ \ae) or by applying diacritical marks + to a~\gls*{latinchar} or characters (e.g.\ \'a or \o). + See also \gls{nonlatinchar}.} +} + +\newglossaryentry{latexexlatinchar}{% + name={Standard \LaTeX\ Extended Latin Character\itermdef{standard +\LaTeX\ extended Latin character}}, + text={standard \LaTeX\ extended Latin character\iterm{standard +\LaTeX\ extended Latin character}}, + sort={standard LaTeX extended Latin character}, + description={An \gls{exlatinchar} that can be created by a~core +\LaTeX\ command, such as \cs{o} (\o) or \cs{'}\texttt{e} (\'e). + That is, the character can be produced without the need to load + a~particular package.} +} + +\newglossaryentry{nonlatinchar}{% + name={Non-Latin Character\itermdef{non-Latin character}}, + text={non-Latin character\iterm{non-Latin character}}, + sort={non-Latin character}, + description={An \gls{exlatinchar} or a~character that isn't + a~\gls{latinchar}.} +} + +\newglossaryentry{latinalph}{% + name={Latin Alphabet\itermdef{Latin alphabet}}, + text={Latin alphabet\iterm{Latin alphabet}}, + sort={Latin alphabet}, + description={The alphabet consisting of \glspl{latinchar}. + See also \gls{exlatinalph}.} +} + +\newglossaryentry{exlatinalph}{% + name={Extended Latin Alphabet\itermdef{Extended Latin Alphabet}}, + text={extended Latin alphabet}, + sort={extended Latin alphabet}, + description={An alphabet consisting of \glspl{latinchar} + and \glspl{exlatinchar}.} +} + +\newglossaryentry{nonlatinalph}{% + name={Non-Latin Alphabet\itermdef{Non-Latin Alphabet}}, + text={non-Latin alphabet}, + sort={non-Latin alphabet}, + description={An alphabet consisting of \glspl{nonlatinchar}.} +} + +\newglossaryentry{glossaries-extra}{% + name={\styfmt{glossaries-extra}}, + sort={glossaries-extra}, + description={A separate package that extends the + \styfmt{glossaries} package, providing new features or improving + existing features. If you want to use \styfmt{glossaries-extra}, + you must have both the \styfmt{glossaries} package and the + \styfmt{glossaries-extra} package installed.} +} + +\ifpdf +\externaldocument{glossaries-code} +\fi + +\doxitem{Option}{option}{package options} +\doxitem{GlsKey}{key}{glossary keys} +\doxitem{Style}{style}{glossary styles} +\doxitem{Counter}{counter}{glossary counters} + +\setcounter{IndexColumns}{2} + +\newcommand*{\tick}{\ding{51}} + +\newcommand*{\yes}{\ding{52}} +\newcommand*{\no}{\ding{56}} + +\newcommand*{\proyes}{\textcolor{green}{\yes}} +\newcommand*{\prono}{\textcolor{red}{\no}} + +\newcommand*{\conyes}{\textcolor{red}{\yes}} +\newcommand*{\conno}{\textcolor{green}{\no}} + +\makeatletter +\newcommand{\fnsymmark}[1]{#1} +\newcommand*{\fnsym}[1]{\textsuperscript{\fnsymmark{% + \ifcase#1\or \textasteriskcentered \or \textdagger + \or \textdaggerdbl \or \textsection + \or $\lozenge$ \or \textparagraph + \or \#\or {\fontfamily{cmr}\selectfont\textreferencemark}% + \or \@nlctdoc@if@usingtexht{\HCode{&\#x2051;}}{\shortstack{*\\[-1.5ex]*}}% + \or $\star$ + \or \ding{94}% + \else + \number#1 + \fi +}}}% +\newcommand*{\optionlabel}[1]{% + \@glstarget{option#1}{Option~#1}} +\makeatother + +\newcounter{option} +\newcommand{\optionsec}[2][\opttitle]{% + \def\opttitle{\appfmt{#2}}% + \refstepcounter{option}% + \pdfbookmark[2]{Option~\theoption\space (#2)}{option\theoption}% + \subsection*{\protect\optionlabel{\theoption} (#1)}% +} + +\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}} + + +\newcommand*{\ifirstuse}{\iterm{first use}} +\newcommand*{\ifirstuseflag}{\iterm{first use>flag}} +\newcommand*{\ifirstusetext}{\iterm{first use>text}} + +\newcommand*{\firstuse}{\gls{firstuse}} +\newcommand*{\firstuseflag}{\gls{firstuseflag}} +\newcommand*{\firstusetext}{\gls{firstusetext}} + + +\newcommand*{\istkey}[1]{\appfmt{#1}\index{makeindex=\appfmt{makeindex}>#1=\texttt{#1}|hyperpage}} +\newcommand*{\locfmt}[1]{\texttt{#1}\SpecialMainIndex{#1}} +\newcommand*{\mkidxspch}{\index{makeindex=\appfmt{makeindex}>special characters|hyperpage}} + +\newcommand*{\mkidxopt}[1]{\texttt{-#1}\index{makeindex=\appfmt{makeindex}>#1=\texttt{-#1}|hyperpage}} + +\newcommand*{\xdyopt}[1]{\texttt{-#1}\index{xindy=\appfmt{xindy}>#1=\texttt{-#1}|hyperpage}} + +\newcommand*{\mkglsopt}[1]{\texttt{-#1}\index{makeglossaries=\appfmt{makeglossaries}>#1=\texttt{-#1}|hyperpage}} + +\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}} +\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}} +\newcommand*{\optfmt}[1]{\textsf{#1}} +\newcommand*{\field}[1]{\optfmt{#1}\index{internal fields:>#1=\protect\optfmt{#1}|main}} + +\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\ttfamily#1}|main}} + +\newcommand*{\acrstyle}[1]{\textsf{#1}\index{acronym styles:>#1={\protect\ttfamily#1}|main}} + +\newcounter{sample} +\newcommand{\exitem}[2][sample]{% + \item[\texttt{#1#2.tex}]% + \refstepcounter{sample}\label{ex:#1#2}} + +\newenvironment{samplelist}% +{\begin{description}}% +{\end{description}} + +\newcommand*{\samplefile}[2][sample]{% + \hyperref[ex:#1#2]{\texttt{#1#2.tex}}} + +\ifpdf + \newcommand*{\htmldoc}[2]{\qt{#1}} +\else + \newcommand*{\htmldoc}[2]{\href{#2.html}{\qt{#1}}} +\fi + +\begin{document} +\MakeShortVerb{"} +\DeleteShortVerb{\|} + + \title{User Manual for glossaries.sty v4.42} + \author{Nicola L.C. Talbot\\% + \url{http://www.dickimaw-books.com/}} + + \date{2019-01-06} + \maketitle + +\begin{abstract} +The \styfmt{glossaries} package provides a means to define terms or +abbreviations or symbols that can be referenced within your document. +Sorted lists with collated \glslink{entrylocation}{locations} can be +generated either using \TeX\ or using a supplementary \gls{indexingapp}. + +Additional features not provided here may be available through +the extension package \gls{glossaries-extra} which, if required, +needs to be installed separately. New features will be added to +\gls*{glossaries-extra}. Versions of the \styfmt{glossaries} +package after v4.21 will mostly be just bug fixes. Note that +\gls{glossaries-extra} provides an extra indexing option +(\gls{bib2gls}) which isn't available with just the base +\sty{glossaries} package. +\end{abstract} + +If you require multilingual support you must also separately install +the relevant language module. Each language module is distributed +under the name \texttt{glossaries-}\meta{language}, where \meta{language} is the +root language name. For example, \texttt{glossaries-french} +or \texttt{glossaries-german}. If a language module is required, +the \styfmt{glossaries} package will automatically try to load it and +will give a warning if the module isn't found. See +\sectionref{sec:languages} for further details. +If there isn't any support available for your language, use +the \pkgopt{nolangwarn} package option to suppress the warning +and provide your own translations. (For example, use +the \gloskey[printglossary]{title} key in \cs{printglossary}.) + +The \styfmt{glossaries} package requires a number of other packages +including, but not limited to, \sty{tracklang}, \sty{mfirstuc}, +\sty{etoolbox}, +\sty{xkeyval} (at least version dated 2006/11/18), \sty{textcase}, +\sty{xfor}, \sty{datatool-base} (part of the \sty{datatool} bundle) and \sty{amsgen}. These +packages are all available in the latest \TeX~Live and Mik\TeX\ +distributions. If any of them are missing, please update your +\TeX\ distribution using your update manager. +For help on this see, for example, +\href{http://tex.stackexchange.com/questions/55437/how-do-i-update-my-tex-distribution}{How +do I update my \TeX\ distribution?} +or (for Linux users) +\href{http://tex.stackexchange.com/questions/14925/updating-tex-on-linux}{Updating +\TeX\ on Linux}. + +Note that occasionally you may find that certain packages need to be +loaded \emph{after} packages that are required by \styfmt{glossaries}. For +example, a package \meta{X} might need to be loaded after \sty{amsgen}. In +which case, load the required package first (for example, +\sty{amsgen}), then \meta{X}, and finally load \styfmt{glossaries}. + +\begin{important} +Documents have wide-ranging styles when it comes to presenting glossaries +or lists of terms or notation. People have their own preferences and +to a large extent this is determined by the kind of information that +needs to go in the glossary. They may just have symbols with +terse descriptions or they may have long technical words with +complicated descriptions. The \styfmt{glossaries} package is +flexible enough to accommodate such varied requirements, but this +flexibility comes at a price: a~big manual. + +\aargh\ If you're freaking out at the size of this manual, start with +\texttt{glossariesbegin.pdf} (\qt{The glossaries package: a guide +for beginnners}). You should find it in the same directory as this +document or try \texttt{texdoc glossariesbegin.pdf}. Once you've got +to grips with the basics, then come back to this manual to find out +how to adjust the settings. +\end{important} + +\noindent +The \styfmt{glossaries} bundle comes with the following documentation: +\begin{description} +\item[\url{glossariesbegin.pdf}] +If you are a complete beginner, start with +\htmldoc{The glossaries package: a guide for +beginners}{glossariesbegin}. + +\item[\url{glossary2glossaries.pdf}] +If you are moving over from the obsolete \sty{glossary} package, +read \htmldoc{Upgrading from the glossary package to the +glossaries package}{glossary2glossaries}. + +\item[glossaries-user.pdf] +This document is the main user guide for the \styfmt{glossaries} +package. + +\item[\url{glossaries-code.pdf}] +Advanced users wishing to know more about the inner workings of all the +packages provided in the \styfmt{glossaries} bundle should read +\qt{Documented Code for glossaries v4.42}. + +\item[INSTALL] Installation instructions. + +\item[CHANGES] Change log. + +\item[README] Package summary. + +\end{description} +Related resources: +\begin{itemize} +\item \styfmt{glossaries-extra} and \gls{bib2gls}: An Introductory +Guide. (\href{http://mirrors.ctan.org/support/bib2gls/bib2gls-begin.pdf}{\texttt{bib2gls-begin.pdf}}). + + +\item \href{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries} +FAQ} + +\item \href{http://www.dickimaw-books.com/gallery/#glossaries}{\styfmt{glossaries} +gallery} + +\item +\href{http://www.dickimaw-books.com/gallery/glossaries-styles/}{a +summary of all glossary styles provided by \styfmt{glossaries}} + +\item +\href{http://www.dickimaw-books.com/gallery/glossaries-performance.shtml}{\styfmt{glossaries} +performance} (comparing document build times for the different +options provided by \styfmt{glossaries} and \styfmt{glossaries-extra}). + +\item \href{http://www.dickimaw-books.com/latex/thesis/}{Using LaTeX to Write a PhD Thesis} +(chapter 6). + +\item +\href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build} + +\item The +\href{http://ctan.org/pkg/glossaries-extra}{\styfmt{glossaries-extra} package} + +\item \href{http://ctan.org/pkg/bib2gls}{\appfmt{bib2gls}} +\end{itemize} + +\begin{important} +If you use \sty{hyperref} and \styfmt{glossaries}, you must load +\sty{hyperref} \emph{first}. Similarly the \sty{doc} package must +also be loaded before \styfmt{glossaries}. (If \sty{doc} is loaded, +the file extensions for the default main glossary are changed to +\filetype{gls2}, \filetype{glo2} and \filetype{.glg2} to avoid +conflict with \sty{doc}'s changes +glossary.)\hypertarget{pdflatexnote}{}% + +If you are using \sty{hyperref}, it's best to use \app{pdflatex} +rather than \app{latex} (DVI format) as \appfmt{pdflatex} deals with +hyperlinks much better. If you use the DVI format, you will +encounter problems where you have long hyperlinks or hyperlinks in +subscripts or superscripts. This is an issue with the DVI format not +with \styfmt{glossaries}. If you really need to use the DVI format +and have a problem with hyperlinks in maths mode, I recommend you use +\gls{glossaries-extra} with the \texttt{hyperoutside} and +\texttt{textformat} attributes set to appropriate values +for problematic entries. +\end{important} + +\clearpage +\pdfbookmark[0]{Contents}{contents} +\tableofcontents +\clearpage +\pdfbookmark[0]{List of Examples}{examples} +\listofexamples +\clearpage +\pdfbookmark[0]{List of Tables}{tables} +\listoftables + +\clearpage +\printglossaries + +\glsresetall + + \chapter{Introduction} +\label{sec:intro} + +The \styfmt{glossaries} package is provided to assist generating +lists of terms, symbols or abbreviations. (For convenience, these +lists are all referred to as glossaries in this manual.) +The package has a certain amount of flexibility, allowing the +user to customize the format of the glossary and define multiple +glossaries. It also supports glossary styles that +include symbols (in addition to a name and description) for glossary +entries. There is provision for loading a database of glossary +terms. Only those terms indexed\footnote{That is, if the term has been +referenced using any of the commands described in +\sectionref{sec:glslink} and \sectionref{sec:glsadd} or via +\ics{glssee} (or the \gloskey{see} key) or commands such as +\ics{acrshort}.}\ in the document will be added to the glossary. + +The \styfmt{glossaries-extra} package, which is distributed as a +separated bundle, extends the capabilities of +the \styfmt{glossaries} package. The simplest document can be +created with \styfmt{glossaries-extra} (which internally loads the +\styfmt{glossaries} package): +\begin{verbatim} +\documentclass{article} + +\usepackage[ + sort=none,% no sorting or indexing required + abbreviations,% create list of abbreviations + symbols,% create list of symbols + postdot % append a full stop after the descriptions +]{glossaries-extra} + +\newglossaryentry % provided by glossaries.sty + {cafe}% label + {% definition: + name={caf\'e}, + description={small restaurant selling refreshments} + } + +\newabbreviation % provided by glossaries-extra.sty + {html}% label + {HTML}% short form + {hypertext markup language}% long form + +\glsxtrnewsymbol % provided by glossaries-extra.sty 'symbols' option + [description={Archimedes' constant}]% options + {pi}% label + {\ensuremath{\pi}}% symbol + +\begin{document} +First use: \gls{cafe}, \gls{html}, \gls{pi}. +Next use: \gls{cafe}, \gls{html}, \gls{pi}. + +\printunsrtglossaries % list all defined entries +\end{document} +\end{verbatim} + +\textbf{The \styfmt{glossaries} package replaces the \sty{glossary} +package which is now obsolete.} Please see the document +\qtdocref{Upgrading from the glossary package to the glossaries +package}{glossary2glossaries} for assistance in upgrading. + +One of the strengths of this package is its flexibility, however +the drawback of this is the necessity of having a large manual +that covers all the various settings. If you are daunted by the +size of the manual, try starting off with the much shorter +\docref{guide for beginners}{glossariesbegin}. + +\begin{important} +There's a~common misconception that you have to have Perl installed +in order to use the \styfmt{glossaries} package. Perl is \emph{not} +a~requirement but it does increase the available options, +particularly if you use an \gls{exlatinalph} or a~\gls{nonlatinalph}. +\end{important} + +This document uses the \styfmt{glossaries} package. For example, +when viewing the PDF version of this document in a +hyperlinked-enabled PDF viewer (such as Adobe Reader or Okular) if +you click on the word \qt{\gls{xindy}} you'll be taken to the entry +in the glossary where there's a brief description of +the term \qt{\gls*{xindy}}. This is the way the \styfmt{glossaries} +mechanism works. An \gls{indexingapp} is used to generated the +sorted list of terms. The \glspl{indexingapp} are \gls{cli} tools, +which means they can be run directly from a command prompt or terminal, or can +be integrated into some text editors, or you can use a build tool +such as \app{arara} to run them. + +The remainder of this introductory section covers the following: +\begin{itemize} +\item \sectionref{sec:indexingoptions} lists the available indexing +options. + +\item \sectionref{sec:samples} lists the sample documents provided +with this package. + +\item \sectionref{sec:lipsum} lists the dummy glossary files that +may be used for testing. + +\item \sectionref{sec:languages} provides information for users who +wish to write in a language other than English. + +\item \sectionref{sec:makeglossaries} describes how to use an +\gls{indexingapp} to create the sorted glossaries for your document +(\optsor23). + +\end{itemize} + +\section{Indexing Options} +\label{sec:indexingoptions} + +The basic idea behind the \styfmt{glossaries} package is that you +first define your entries (terms, symbols or abbreviations). Then +you can reference these within your document (like \cs{cite} or +\cs{ref}). You can also, optionally, display a~list of the entries +you have referenced in your document (the glossary). This last part, +displaying the glossary, is the part that most new users find +difficult. There are three options available with the base +\styfmt{glossaries} package and two further options with the +extension package \gls{glossaries-extra}. +An overview of these options is given in +\tableref{tab:options}. + +If you are developing a class or package that loads +\styfmt{glossaries}, I recommend that you don't force the user into +a particular indexing method by adding an unconditional \cs{makeglossaries} +into your class or package code. Aside from forcing the user into a +particular indexing method, it means that they're unable to use any +commands that must come before \cs{makeglossaries} (such as +\cs{newglossary}) and they can't switch off the indexing whilst +working on a draft document. + +For a comparison of the various methods when used with large entry +sets or when used with symbols such as \cs{alpha}, see the +\href{http://www.dickimaw-books.com/gallery/glossaries-performance.shtml}{\styfmt{glossaries} performance page}. + +\begin{table}[htbp] + \caption{Glossary Options: Pros and Cons} + \label{tab:options} + {% + \renewcommand{\fnsymmark}[1]{\rlap{#1}}% + \setlength{\tabcolsep}{3pt}% + \centering + \begin{tabular}{@{}>{\raggedright\small}p{0.35\textwidth}ccccc@{}} + & \bfseries \opt1 & \bfseries \opt2 & \bfseries \opt3 + & \bfseries \opt4 & \bfseries \opt5\\ + Requires \gls{glossaries-extra}? & + \conno & \conno & \conno & \conyes & \conyes\\ + Requires an external application? & + \conno & \conyes & \conyes & \conyes & \conno\\ + Requires Perl? & + \conno & \conno & \conyes & \conno & \conno\\ + Requires Java? & + \conno & \conno & \conno & \conyes & \conno\\ + Can sort \glspl{exlatinalph} + or \glspl{nonlatinalph}? & + \prono\fnsym{1} & \prono & \proyes & \proyes & N/A\\ + Efficient sort algorithm? & + \prono & \proyes & \proyes & \proyes & N/A\\ + Can use a different sort method for each glossary? & + \proyes + & \prono\fnsym{2} + & \prono\fnsym{2} & \proyes & N/A\\ + Any problematic sort values? & + \conyes & \conyes & \conyes & \conno & \conno\fnsym{3}\\ + Are entries with identical sort values treated as separate unique + entries? & + \proyes & \proyes & \prono\fnsym{4} & \proyes & \proyes\\ + Can automatically form ranges in the location lists? & + \prono & \proyes & \proyes & \proyes & \prono\\ + Can have non-standard locations in the location lists? & + \proyes & \prono + & \proyes\fnsym{5} + & \proyes + & \proyes\fnsym{6}\\ + Maximum hierarchical depth (style-dependent) & + $\infty$\fnsym{7} & 3 & $\infty$ & $\infty$ & $\infty$\\ + \ics{glsdisplaynumberlist} reliable? & + \proyes & \prono & \prono & \proyes & \prono\\ + \ics{newglossaryentry} allowed in \env{document} environment? + (Not recommended.) & + \no & \yes & \yes & \no\fnsym{8} & \yes\fnsym{9}\\ + Requires additional write registers? & + \conno & \conyes & \conyes & \conno & \conno\fnsym{10}\\ + Default value of \pkgopt{sanitizesort} package option & + \texttt{false} & \texttt{true} & \texttt{true} + & \texttt{true}\fnsym{11} + & \texttt{true}\fnsym{11} + \end{tabular} + \par + }\par + \smallskip + \hrulefill\par + \smallskip\footnotesize + \fnsym{1} Strips standard \LaTeX\ accents +(that is, accents generated by core \LaTeX\ commands) so, +for example, \ics{AA} is treated the same as A.\par + \fnsym{2} Only with the hybrid method provided with \sty{glossaries-extra}.\par + \fnsym{3} Provided \pkgopt[none]{sort} is used.\par + \fnsym{4} Entries with the same sort value are merged.\par + \fnsym{5} Requires some setting up.\par + \fnsym{6} The locations must be set explicitly +through the custom \field{location} field provided by +\styfmt{glossaries-extra}.\par + \fnsym{7} Unlimited but unreliable.\par + \fnsym{8} Entries are defined in \texttt{.bib} +format. \cs{newglossaryentry} should not be used explicitly.\par + \fnsym{9} Provided \pkgoptfmt{docdefs=true} or +\pkgoptfmt{docdefs=restricted} but not recommended.\par + \fnsym{10} Provided \pkgoptfmt{docdefs=false} or +\pkgoptfmt{docdefs=restricted}.\par + \fnsym{11} Irrelevant with \pkgopt[none]{sort}. (The \optfmt{record=only} + option automatically switches this on.) +\par +\end{table} + +\optionsec[\TeX]{TeX} + +This option doesn't require an external \gls{indexingapp} but, with +the default alphabetic sorting, it's very slow with severe limitations. +If you want a sorted list, it doesn't work well for +\glspl{exlatinalph} or \glspl{nonlatinalph}. However, if you use +the \pkgopt[false]{sanitizesort} package option (the default for +Option~1) then the \glslink{latexexlatinchar}{standard \LaTeX\ +accent commands} will be ignored, so if an entry's name is set to +\verb|{\'e}lite| then the sort value will default to \texttt{elite} if +\pkgopt[false]{sanitizesort} is used and will default to +\verb|\'elite| if \pkgopt[true]{sanitizesort} is used. If you have +any other kinds of commands that don't expand to ASCII characters, +such as \cs{alpha} or \cs{si}, then you must use +\pkgopt[true]{sanitizesort} or change the sort method +(\pkgopt[use]{sort} or \pkgopt[def]{sort}) in the package options +or explicitly set the \gloskey{sort} key when you define the +relevant entries. For example: +\begin{verbatim} +\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, + sort={alpha},description={...}} +\end{verbatim} + +This option works best with the \pkgopt[def]{sort} or +\pkgopt[use]{sort} setting. For any +other setting, be prepared for a long document build time, +especially if you have a lot of entries defined. \textbf{This +option is intended as a last resort for alphabetical sorting.} +This option allows a mixture of sort methods. (For example, +sorting by word order for one glossary and order of use for another.) +This option is not suitable for hierarchical glossaries and does +not form ranges in the \glspl{numberlist}. If you really can't use an +\gls{indexingapp} consider using \opt{5} instead. + + \begin{enumerate} + \item Add +\begin{verbatim} +\makenoidxglossaries +\end{verbatim} + to your preamble (before you start defining your entries, as described in + \sectionref{sec:newglosentry}). + + \item Put +\begin{verbatim} +\printnoidxglossary +\end{verbatim} + where you want your list of entries to appear (described in + \sectionref{sec:printglossary}). Alternatively, to display all + glossaries use the iterative command: +\begin{verbatim} +\printnoidxglossaries +\end{verbatim} + + \item Run \LaTeX\ twice on your document. (As you would do to + make a~table of contents appear.) For example, click twice on + the \qt{typeset} or \qt{build} or \qt{PDF\LaTeX} button in your editor. + \end{enumerate} + +Complete example: +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\makenoidxglossaries % use TeX to sort +\newglossaryentry{sample}{name={sample}, + description={an example}} +\begin{document} +\gls{sample}. +\printnoidxglossary +\end{document} +\end{verbatim} + +\optionsec{makeindex} + +This option uses a~\gls{cli} application called \gls{makeindex} to sort +the entries. This application comes with all modern \TeX\ distributions, +but it's hard-coded for the non-extended \gls{latinalph}. It can't +correctly sort accent commands (such as \cs{'} or \cs{c}) and fails +with UTF-8 characters, especially for any sort values that start +with a UTF-8 character (as it separates the octets resulting in an +invalid file encoding). This process involves making \LaTeX\ write +the glossary information to a temporary file which \gls{makeindex} +reads. Then \gls{makeindex} writes a~new file containing the code +to typeset the glossary. Then \cs{printglossary} reads this file in +on the next run. + +This option works best if you want to sort entries according to the +English alphabet and you don't want to install Perl (or Java or +you don't want to use \gls{glossaries-extra}). This method can +also work with the restricted shell escape since \gls{makeindex} +is considered a trusted application. (So you should be able to +use the \pkgopt{automake} package option provided the shell +escape hasn't been completely disabled.) + +This method can form ranges in the \gls{numberlist} but only +accepts limited number formats: \cs{arabic}, \cs{roman}, +\cs{Roman}, \cs{alph} and \cs{Alph}. + +This option does not allow a mixture of sort methods. +All glossaries must be sorted according to the same method: +word\slash letter ordering or order of use or order of definition. +If you need word ordering for one glossary and letter ordering +for another you'll have to explicitly call \gls{makeindex} for +each glossary type. +(The \sty{glossaries-extra} package allows a hybrid mix of +\optsand12 to provide word\slash letter ordering with \opt2 and order +of use\slash definition with \opt1. See the \sty{glossaries-extra} +documentation for further details.) + + \begin{enumerate} + \item If you want to use \gls{makeindex}['s] \mkidxopt{g} option + you must change the quote character using \ics{GlsSetQuote}. For example: +\begin{verbatim} +\GlsSetQuote{+} +\end{verbatim} + This must be used before \cs{makeglossaries}. + Note that if you are using \sty{babel}, the shorthands aren't + enabled until the start of the document, so you won't be able to use + the shorthands in definitions made in the preamble. + + \item Add +\begin{verbatim} +\makeglossaries +\end{verbatim} +to your preamble (before you start + defining your entries, as described in + \sectionref{sec:newglosentry}). + + \item Put +\begin{verbatim} +\printglossary +\end{verbatim} + where you want your list of entries to appear (described in + \sectionref{sec:printglossary}). Alternatively, to display all + glossaries use the iterative command: +\begin{verbatim} +\printglossaries +\end{verbatim} + + \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. (If you use + \sty{glossaries-extra} you'll see the section heading and some + boilerplate text.) + + \item Run \gls{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 possible.) If you don't know + how to use the command prompt, then you can probably access + \gls{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 + simplest approach is to use \app{arara} and add the following + comment lines to the start of your document: +\begin{alltt} +\% arara:\ pdflatex +\% arara:\ makeglossaries +\% arara:\ pdflatex +\end{alltt} + (Replace \texttt{makeglossaries} with + \texttt{makeglossaries-lite} if you don't have Perl installed.) + + The default sort is word order (\qt{sea lion} comes before \qt{seal}). + If you want letter ordering you need to add the \mkidxopt{l} + switch: +\begin{verbatim} +makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo +\end{verbatim} + (See \sectionref{sec:makeindexapp} for further details on using + \gls*{makeindex} explicitly.) If you use \gls{makeglossaries} + or \gls{makeglossaries-lite.lua} then use the \pkgopt[letter]{order} + package option and the \mkidxopt{l} option will be added + automatically. + + \item Once you have successfully completed the previous step, + you can now run \LaTeX\ on your document again. You'll need to + repeat the process if you have used the \pkgopt{toc} option + (unless you're using \sty{glossaries-extra}) to ensure the + section heading is added to the table of contents. You'll also + need to repeat the process if you have any cross-references + which can't be indexed until the glossary file has been created. + \end{enumerate} + +Complete example: +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\makeglossaries % open glossary files +\newglossaryentry{sample}{name={sample}, + description={an example}} +\begin{document} +\gls{sample}. +\printglossary +\end{document} +\end{verbatim} + +\optionsec{xindy} + +This option uses a~\gls{cli} application called +\gls{xindy} to sort the entries. This application is more flexible than +\texttt{makeindex} and is able to sort \glspl{exlatinalph} or +\glspl{nonlatinalph}, however it does still have some limitations. + +The \gls{xindy} application comes with both \TeX~Live and +MiK\TeX, but since \gls{xindy} is a Perl script, you will also need +to install Perl, if you don't already have it. In a~similar way to +\opt2, this option involves making \LaTeX\ write the glossary +information to a~temporary file which \gls{xindy} reads. Then +\gls{xindy} writes a~new file containing the code to typeset the +glossary. Then \cs{printglossary} reads this file in on the next run. + +This is the best option with just the base \styfmt{glossaries} +package if you want to sort according to a~language other than +English or if you want non-standard location lists, but it can +require some setting up (see \sectionref{sec:xindy}). There are +some problems with certain sort values: +\begin{itemize} + \item entries with the same sort value are merged by \gls*{xindy} + into a single glossary line so you must make sure that each entry + has a unique sort value; + \item \gls*{xindy} forbids empty sort values; + \item \gls*{xindy} automatically strips control sequences, the math-shift + character \verb|$| and braces \verb|{}| from the sort value, + which is usually desired but this can cause the sort value to + collapse to an empty string which \gls*{xindy} forbids. +\end{itemize} +In these problematic cases, you must set the \gloskey{sort} field +explicitly. For example: +\begin{verbatim} +\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, + sort={alpha},description={...}} +\end{verbatim} + +All glossaries must be sorted according to the same method +(word/letter ordering, order of use, or order of definition). +(The \sty{glossaries-extra} package allows a hybrid mix of +\optsand13 to provide word\slash letter ordering with \opt3 and order +of use\slash definition with \opt1. See the \sty{glossaries-extra} +documentation for further details.) + +\begin{enumerate} + \item Add the \pkgopt{xindy} option to the \styfmt{glossaries} +package option list: +\begin{verbatim} +\usepackage[xindy]{glossaries} +\end{verbatim} + If you are using a non-Latin script you'll also need to either + switch off the creation of the number group: +\begin{verbatim} +\usepackage[xindy={glsnumbers=false}]{glossaries} +\end{verbatim} + or use either \cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter} or + \cs{GlsSetXdyNumberGroupOrder}\marg{spec} to indicate where the number + group should be placed (see \sectionref{sec:xindy}). + + \item Add \cs{makeglossaries} to your preamble (before you start + defining your entries, as described in \sectionref{sec:newglosentry}). + + \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. (If you're using the + extension package \sty{glossaries-extra}, you'll see the section + header and some boilerplate text.) + + \item Run \gls{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, for example, + \xdyopt{L}\texttt{ german }\xdyopt{C}\texttt{ din5007-utf8}.) + Note that it's much simpler to use \gls{makeglossaries} instead: +\begin{verbatim} +makeglossaries myDoc +\end{verbatim} + (Remember that \gls{xindy} is a Perl script so if you can use + \gls{xindy} then you can also use \gls{makeglossaries}, and if + you don't want to use \gls{makeglossaries} because you don't + want to install Perl, then you can't use \gls{xindy} either.) + + If you don't know how to use the command prompt, then you can + probably access \gls{xindy} or \gls{makeglossaries} 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. Again, + a convenient method is to use \appfmt{arara} and add the follow comment + lines to the start of your document: +\begin{alltt} +\% arara:\ pdflatex +\% arara:\ makeglossaries +\% arara:\ pdflatex +\end{alltt} + + The default sort is word order (\qt{sea lion} comes before \qt{seal}). + If you want letter ordering you need to add the + \pkgopt[letter]{order} package option: +\begin{verbatim} +\usepackage[xindy,order=letter]{glossaries} +\end{verbatim} + (and return to the previous step). This option is picked up + by \gls{makeglossaries}. If you are explicitly using \gls{xindy} + then you'll need to add \texttt{-M ord/letorder} to the options list. + See \sectionref{sec:xindyapp} for further details on using + \gls*{xindy} explicitly. + + \item Once you have successfully completed the previous step, + you can now run \LaTeX\ on your document again. As with the + previous option, you may need to repeat the process to ensure + the table of contents and cross-references are resolved. + +\end{enumerate} + +Complete example: +\begin{verbatim} +\documentclass{article} +\usepackage[xindy]{glossaries} +\makeglossaries % open glossary files +\newglossaryentry{sample}{name={sample}, + description={an example}} +\begin{document} +\gls{sample}. +\printglossary +\end{document} +\end{verbatim} + +\optionsec{bib2gls} + +This option is only available with the extension package +\gls{glossaries-extra}. This method uses \gls{bib2gls} to both +fetch entry definitions from \texttt{.bib} files and to +hierarchically sort and collate. + +All entries must be provided in one or more \texttt{.bib} files. +(See the \gls{bib2gls} user manual for the required format.) The +\sty{glossaries-extra} package needs to be loaded with the +\pkgoptfmt{record} package option +\begin{verbatim} +\usepackage[record]{glossaries-extra} +\end{verbatim} +or (equivalently) +\begin{verbatim} +\usepackage[record=only]{glossaries-extra} +\end{verbatim} +(It's possible to use a hybrid of this method and \optsor23 with +\pkgoptfmt{record=alsoindex} but in general there is little need +for this and it complicates the build process.) + +Each resource set is loaded with \cs{GlsXtrLoadResources}\oarg{options}. +For example: +\begin{verbatim} +\GlsXtrLoadResources +[% definitions in entries1.bib and entries2.bib: + src={entries1,entries2}, + sort={de-CH-1996}% sort according to this locale +] +\end{verbatim} +You can have multiple resource commands. + +The glossary is displayed using +\begin{verbatim} +\printunsrtglossary +\end{verbatim} +Alternatively all glossaries can be displayed using the iterative +command: +\begin{verbatim} +\printunsrtglossaries +\end{verbatim} +The document is build using: +\begin{verbatim} +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +\end{verbatim} +If letter groups are required, you need the \verb|--group| switch: +\begin{verbatim} +bib2gls --group myDoc +\end{verbatim} +Unlike \optsand23, this method doesn't create a file containing +the typeset glossary but simply determines which entries are +needed for the document, their associated locations and (if +required) their associated letter group. This option allows +a mixture of sort methods. (For example, sorting by word order +for one glossary and order of use for another or even sorting +one block of the glossary differently to another block in the +same glossary.) + +This method supports Unicode and (with at least Java~8) uses +the Common Locale Data Repository, which provides more extensive +language support than \gls{xindy}.\footnote{Except for Klingon, +which is supported by \gls{xindy}, but not by the +CLDR.}\ The locations in the +\gls{numberlist} may be in any format. If \gls{bib2gls} can +deduce a numerical value it will attempt to form ranges otherwise +it will simply list the locations. + +Complete example: +\begin{verbatim} +\documentclass{article} +\usepackage[record]{glossaries-extra} +\GlsXtrLoadResources[src={entries}] +\begin{document} +\gls{sample}. +\printunsrtglossary +\end{document} +\end{verbatim} +where \texttt{entries.bib} contains +\begin{verbatim} +@entry{sample, + name={sample}, + description={an example} +} +\end{verbatim} +See the \gls{bib2gls} user manual for further details. + +\optionsec[no sorting]{no sorting} + +This option is only available with the extension package +\gls{glossaries-extra}. No \gls{indexingapp} is required. This +method is best used with the package option \pkgopt[none]{sort}. +\begin{verbatim} +\usepackage[sort=none]{glossaries-extra} +\end{verbatim} +There's no \qt{activation} command (such as \cs{makeglossaries} +for \optsand23). + +All entries must be defined before the glossary is displayed +(preferably in the preamble) in the required order, and child +entries must be defined immediately after their parent entry +if they must be kept together in the glossary + +The glossary is displayed using +\begin{verbatim} +\printunsrtglossary +\end{verbatim} +Alternatively all glossaries can be displayed using the iterative +command: +\begin{verbatim} +\printunsrtglossaries +\end{verbatim} +This will display \emph{all} defined entries, regardless of +whether or not they have been used in the document. The +\glspl{numberlist} have to be set explicitly otherwise they won't +appear. Note that this uses the same command for displaying the +glossary as \opt4. This is because \gls{bib2gls} takes advantage +of this method by defining the wanted entries in the required order and +setting the locations (and letter group information, if required). + +This just requires a single \LaTeX\ call +\begin{verbatim} +pdflatex myDoc +\end{verbatim} +unless the glossary needs to appear in the table of contents, in which case +a second run is required. +\begin{verbatim} +pdflatex myDoc +pdflatex myDoc +\end{verbatim} +(Naturally if the document also contains citations, and so on, +then additional steps are required. Similarly for all the other +options above.) + +Complete example: +\begin{verbatim} +\documentclass{article} +\usepackage[sort=none]{glossaries-extra} +\newglossaryentry{sample}{name={sample}, + description={an example}} +\begin{document} +\gls{sample}. +\printunsrtglossary +\end{document} +\end{verbatim} +See the \sty{glossaries-extra} documentation for +further details. + +\section{Sample Documents} +\label{sec:samples} + +The \styfmt{glossaries} package is provided with some sample +documents that illustrate the various functions. These should +be located in the \texttt{samples} subdirectory (folder) of the +\styfmt{glossaries} documentation directory. This location varies +according to your operating system and \TeX\ distribution. You +can use \texttt{texdoc} to locate the main glossaries documentation. +For example, in a +\href{http://www.dickimaw-books.com/latex/novices/html/terminal.html}{terminal or command prompt}, type: +\begin{prompt} +texdoc -l glossaries +\end{prompt} +This should display a list of all the files in the glossaries +documentation directory with their full pathnames. (The GUI version +of \texttt{texdoc} may also provide you with the information.) + +If you can't find the sample files on your computer, they are also available +from your nearest CTAN mirror at +\url{http://mirror.ctan.org/macros/latex/contrib/glossaries/samples/}. + +The sample documents are listed below\footnote{Note that although I've written +\texttt{latex} in this section, it's better to use \texttt{pdflatex}, where +possible, for the reasons given \hyperlink{pdflatexnote}{earlier}.} +If you prefer to use UTF-8 aware engines (\texttt{xelatex} or +\texttt{lualatex}) remember that you'll need to switch from +\styfmt{fontenc} \& \styfmt{inputenc} to \styfmt{fontspec} where +appropriate. The \gls{glossaries-extra} package provides some +additional sample files. + +\begin{samplelist} +\exitem[minimal]{gls} This document is a +minimal working example. You can test your installation using this +file. To create the complete document you will need to do the +following steps: + \begin{enumerate} + \item Run \texttt{minimalgls.tex} through \LaTeX\ either by + typing +\begin{prompt} +latex minimalgls +\end{prompt} + in a terminal or by using the relevant button or menu item in + your text editor or front-end. This will create the required + associated files but you will not see the glossary. If you use + PDF\LaTeX\ you will also get warnings about non-existent + references that look something like: +\begin{verbatim} +pdfTeX warning (dest): name{glo:aca} has been +referenced but does not exist, +replaced by a fixed one +\end{verbatim} + These warnings may be ignored on the first run. + + If you get a \verb"Missing \begin{document}" error, then + it's most likely that your version of \sty{xkeyval} is + out of date. Check the log file for a warning of that nature. + If this is the case, you will need to update the \styfmt{xkeyval} + package. + + \item If you have Perl installed, run \gls{makeglossaries} on the document (\sectionref{sec:makeglossaries}). This can + be done on a terminal by typing +\begin{prompt} +makeglossaries minimalgls +\end{prompt} + otherwise do +\begin{prompt} +makeglossaries-lite minimalgls +\end{prompt} + If for some reason you want to call \gls{makeindex} explicitly, you can do this + in a terminal by typing (all on one line): +\begin{prompt} +makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls minimalgls.glo +\end{prompt} + (See \sectionref{sec:makeindexapp} for further details on using + \gls*{makeindex} explicitly.) + + Note that if the file name contains spaces, you will need to use + the double-quote character to delimit the name. + + \item Run \texttt{minimalgls.tex} through \LaTeX\ again (as step~1) + \end{enumerate} +You should now have a complete document. The number following +each entry in the glossary is the location number. By default, this +is the page number where the entry was referenced. + +There are three other files that can be used as a +\href{http://www.dickimaw-books.com/latex/minexample/}{minimal working +example}: \texttt{mwe-gls.tex}, \texttt{mwe-acr.tex} and +\texttt{mwe-acr-desc.tex}. + +\exitem{-noidxapp} This document illustrates how to use the +\styfmt{glossaries} package without an external \gls{indexingapp} (\opt1). +To create the complete document, you need to do: +\begin{prompt} +latex sample-noidxapp +latex sample-noidxapp +\end{prompt} + +\exitem{-noidxapp-utf8} As the previous example, except that it uses +the \sty{inputenc} package. +To create the complete document, you need to do: +\begin{prompt} +latex sample-noidxapp-utf8 +latex sample-noidxapp-utf8 +\end{prompt} + +\exitem{4col} This document illustrates +a four column glossary where the entries have a symbol in addition +to the name and description. To create the complete document, you +need to do: +\begin{prompt} +latex sample4col +makeglossaries sample4col +latex sample4col +\end{prompt} +or +\begin{prompt} +latex sample4col +makeglossaries-lite sample4col +latex sample4col +\end{prompt} +The vertical gap between entries is the +gap created at the start of each group. This can be suppressed +using the \pkgopt{nogroupskip} package option. + +\exitem{Acr} This document has some +sample abbreviations. It also adds the glossary to the table of contents, +so an extra run through \LaTeX\ is required to ensure the document +is up to date: +\begin{prompt} +latex sampleAcr +makeglossaries sampleAcr +latex sampleAcr +latex sampleAcr +\end{prompt} +(or use \gls{makeglossaries-lite.lua}). + +\exitem{AcrDesc} This is similar to +the previous example, except that the abbreviations have an associated +description. As with the previous example, the glossary is added to +the table of contents, so an extra run through \LaTeX\ is required: +\begin{prompt} +latex sampleAcrDesc +makeglossaries sampleAcrDesc +latex sampleAcrDesc +latex sampleAcrDesc +\end{prompt} + +\exitem{Desc} This is similar to the +previous example, except that it defines the abbreviations using +\ics{newglossaryentry} instead of \ics{newacronym}. As with the +previous example, the glossary is added to the table of contents, so +an extra run through \LaTeX\ is required: +\begin{prompt} +latex sampleDesc +makeglossaries sampleDesc +latex sampleDesc +latex sampleDesc +\end{prompt} + +\exitem{CustomAcr} This document has some sample abbreviations with a +custom acronym style. It also adds the glossary to the table of +contents, so an extra run through \LaTeX\ is required: +\begin{prompt} +latex sampleCustomAcr +makeglossaries sampleCustomAcr +latex sampleCustomAcr +latex sampleCustomAcr +\end{prompt} + +\exitem{FnAcrDesc} This is similar to \samplefile{AcrDesc}, except that it +uses the \acrstyle{footnote-sc-desc} style. As with the previous example, +the glossary is added to the table of contents, so an extra run through +\LaTeX\ is required: +\begin{prompt} +latex sampleFnAcrDesc +makeglossaries sampleFnAcrDesc +latex sampleFnAcrDesc +latex sampleFnAcrDesc +\end{prompt} + +\exitem{-FnDesc} This example +defines a custom display format that puts the description in a +footnote on first use. +\begin{prompt} +latex sample-FnDesc +makeglossaries sample-FnDesc +latex sample-FnDesc +\end{prompt} + +\exitem{-custom-acronym} +This document illustrates how to define your own acronym style if +the predefined styles don't suit your requirements. +\begin{prompt} +latex sample-custom-acronym +makeglossaries sample-custom-acronym +latex sample-custom-acronym +\end{prompt} + +\exitem{-crossref} +This document illustrates how to cross-reference entries in the +glossary. +\begin{prompt} +latex sample-crossref +makeglossaries sample-crossref +latex sample-crossref +\end{prompt} + +\exitem{-dot-abbr} This document illustrates how to use the +post link hook to adjust the space factor after abbreviations. +\begin{prompt} +latex sample-dot-abbr +makeglossaries sampledot-abbrf +latex sample-dot-abbr +\end{prompt} + +\exitem{DB} This document illustrates how +to load external files containing the glossary definitions. It also +illustrates how to define a new glossary type. This document has the +\gls{numberlist} suppressed and uses \ics{glsaddall} to add all +the entries to the glossaries without referencing each one +explicitly. To create the document do: +\begin{prompt} +latex sampleDB +makeglossaries sampleDB +latex sampleDB +\end{prompt} +or +\begin{prompt} +latex sampleDB +makeglossaries-lite sampleDB +latex sampleDB +\end{prompt} +The glossary definitions are stored in the accompanying files +\texttt{database1.tex} and \texttt{database2.tex}. If for some +reason you want to call \gls{makeindex} explicitly you must +have a separate call for each glossary: +\begin{enumerate} +\item Create the main glossary (all on one line): +\begin{prompt}\raggedright +makeindex -s sampleDB.ist -t sampleDB.glg -o sampleDB.gls sampleDB.glo +\end{prompt} +\item Create the secondary glossary (all on one line): +\begin{prompt}\raggedright +makeindex -s sampleDB.ist -t sampleDB.nlg -o sampleDB.not sampleDB.ntn +\end{prompt} +Note that both \gls{makeglossaries} and \gls{makeglossaries-lite.lua} do +this all in one call, so they not only make it easier because you +don't need to supply all the switches and remember all the +extensions but they also call \gls{makeindex} the appropriate number of times. +\end{enumerate} + +\exitem{Eq} This document illustrates how +to change the location to something other than the page number. In +this case, the \texttt{equation} counter is used since all glossary +entries appear inside an \env{equation} environment. To create +the document do: +\begin{prompt} +latex sampleEq +makeglossaries sampleEq +latex sampleEq +\end{prompt} + +\exitem{EqPg} This is similar to the +previous example, but the \glspl{numberlist} are a +mixture of page numbers and equation numbers. This example adds the +glossary to the table of contents, so an extra \LaTeX\ run is +required: +\begin{prompt} +latex sampleEqPg +makeglossaries sampleEqPg +latex sampleEqPg +latex sampleEqPg +\end{prompt} + +\exitem{Sec} This document also +illustrates how to change the location to something other than the +page number. In this case, the \texttt{section} counter is used. +This example adds the glossary to the table of contents, so an extra +\LaTeX\ run is required: +\begin{prompt} +latex sampleSec +makeglossaries sampleSec +latex sampleSec +latex sampleSec +\end{prompt} + +\exitem{Ntn} This document illustrates +how to create an additional glossary type. This example adds the +glossary to the table of contents, so an extra \LaTeX\ run is +required: +\begin{prompt} +latex sampleNtn +makeglossaries sampleNtn +latex sampleNtn +latex sampleNtn +\end{prompt} +Note that if you want to call \gls{makeindex} explicitly instead of +using \gls{makeglossaries} or \gls{makeglossaries-lite.lua} then you +need to call \gls{makeindex} twice: +\begin{enumerate} +\item Create the main glossary (all on one line): +\begin{prompt}\raggedright +makeindex -s sampleNtn.ist -t sampleNtn.glg -o sampleNtn.gls sampleNtn.glo +\end{prompt} +\item Create the secondary glossary (all on one line): +\begin{prompt}\raggedright +makeindex -s sampleNtn.ist -t sampleNtn.nlg -o sampleNtn.not sampleNtn.ntn +\end{prompt} +\end{enumerate} + +\exitem{} This document illustrates some of +the basics, including how to create child entries that use the same +name as the parent entry. This example adds the glossary to the +table of contents and it also uses \ics{glsrefentry}, so an extra \LaTeX\ +run is required: +\begin{prompt} +latex sample +makeglossaries sample +latex sample +latex sample +\end{prompt} +You can see the difference between word and letter ordering if you +substitute \pkgopt[word]{order} with \pkgopt[letter]{order}. (Note +that this will only have an effect if you use +\gls{makeglossaries} or \gls{makeglossaries-lite.lua}. +If you use \gls{makeindex} explicitly, you will need to use the +\mkidxopt{l} switch to indicate letter ordering.) + +\exitem{-inline} This document is +like \texttt{sample.tex}, above, but uses the \glostyle{inline} +glossary style to put the glossary in a footnote. + +\exitem{tree} This document illustrates +a hierarchical glossary structure where child entries have different +names to their corresponding parent entry. To create the document +do: +\begin{prompt} +latex sampletree +makeglossaries sampletree +latex sampletree +\end{prompt} + +\exitem{-dual} This document +illustrates how to define an entry that both appears in the list of +acronyms and in the main glossary. To create the document do: +\begin{prompt} +latex sample-dual +makeglossaries sample-dual +latex sample-dual +\end{prompt} + +\exitem{-langdict} This document +illustrates how to use the glossaries package to create English +to French and French to English dictionaries. To create the document +do: +\begin{prompt} +latex sample-langdict +makeglossaries sample-langdict +latex sample-langdict +\end{prompt} + +\exitem{xdy} This document illustrates +how to use the \styfmt{glossaries} package with \gls{xindy} instead +of \gls{makeindex}. The document uses UTF8 encoding (with the +\sty{inputenc} package). The encoding is picked up by +\gls{makeglossaries}. By default, this document will create a +\gls{xindy} style file called \texttt{samplexdy.xdy}, but if you +uncomment the lines +\begin{verbatim} +\setStyleFile{samplexdy-mc} +\noist +\GlsSetXdyLanguage{} +\end{verbatim} +it will set the style file to \texttt{samplexdy-mc.xdy} instead. +This provides an additional letter group for entries starting with +\qt{Mc} or \qt{Mac}. If you use \gls{makeglossaries} or +\gls{makeglossaries-lite.lua}, you don't +need to supply any additional information. If you don't use +\gls*{makeglossaries}, you will need to specify the required +information. Note that if you set the style file to +\texttt{samplexdy-mc.xdy} you must also specify \ics{noist}, +otherwise the \styfmt{glossaries} package will overwrite +\texttt{samplexdy-mc.xdy} and you will lose the \qt{Mc} letter +group. + +To create the document do: +\begin{prompt} +latex samplexdy +makeglossaries samplexdy +latex samplexdy +\end{prompt} +If you don't have Perl installed then you can't use +\gls{makeglossaries}, but you also can't use \gls{xindy}! +However, if for some reason you want to call +\gls{xindy} explicitly instead of using \gls{makeglossaries} (or +\gls{makeglossaries-lite.lua}): +\begin{itemize} +\item if you are using the default style file \texttt{samplexdy.xdy}, then +do (no line breaks): +\begin{prompt}\raggedright +xindy -L english -C utf8 -I xindy -M samplexdy -t samplexdy.glg -o samplexdy.gls samplexdy.glo +\end{prompt} +\item if you are using \texttt{samplexdy-mc.xdy}, then do +(no line breaks): +\begin{prompt}\raggedright +xindy -I xindy -M samplexdy-mc -t samplexdy.glg -o samplexdy.gls samplexdy.glo +\end{prompt} +\end{itemize} + +\exitem{xdy2} This document illustrates +how to use the \styfmt{glossaries} package where the location +numbers don't follow a standard format. This example will only work +with \gls{xindy}. To create the document do: +\begin{prompt} +pdflatex samplexdy2 +makeglossaries samplexdy2 +pdflatex samplexdy2 +\end{prompt} +The explicit \gls{xindy} call is: +\begin{prompt}\raggedright +xindy -L english -C utf8 -I xindy -M samplexdy2 -t samplexdy2.glg -o samplexdy2.gls samplexdy2.glo +\end{prompt} +See \sectionref{sec:xindyloc} for further details. + +\exitem{xdy3} This document is like \samplefile{xdy} but uses the +command \cs{Numberstring} from the \sty{fmtcount} package to +format the page numbers. + +\exitem{utf8} This is another example +that uses \gls{xindy}. Unlike \gls{makeindex}, +\gls{xindy} can cope with \glspl{nonlatinchar}. This +document uses UTF8 encoding. To create the document do: +\begin{prompt} +latex sampleutf8 +makeglossaries sampleutf8 +latex sampleutf8 +\end{prompt} +The explicit \gls{xindy} call is +(no line breaks): +\begin{prompt}\raggedright +xindy -L english -C utf8 -I xindy -M sampleutf8 -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo +\end{prompt} + +If you remove the \pkgopt{xindy} option from \texttt{sampleutf8.tex} +and do: +\begin{prompt} +latex sampleutf8 +makeglossaries sampleutf8 +latex sampleutf8 +\end{prompt} +or +\begin{prompt} +latex sampleutf8 +makeglossaries-lite sampleutf8 +latex sampleutf8 +\end{prompt} +you will see that the entries that start with an \gls{exlatinchar} +now appear in the symbols group, and the word \qt{man\oe uvre} is now +after \qt{manor} instead of before it. If you want to explicitly +call \gls{makeindex} (no line breaks): +\begin{prompt}\raggedright +makeindex -s sampleutf8.ist -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo +\end{prompt} + +\exitem{-index} This document uses +the \styfmt{glossaries} package to create both a glossary and an +index. This requires two \gls{makeglossaries} (or +\gls{makeglossaries-lite.lua}) calls to ensure the +document is up to date: +\begin{prompt} +latex sample-index +makeglossaries sample-index +latex sample-index +makeglossaries sample-index +latex sample-index +\end{prompt} + +\exitem{-newkeys} This document illustrates how add custom keys +(using \cs{glsaddkey}). + +\exitem{-storage-abbr} This document illustrates how add custom +storage keys (using \cs{glsaddstoragekey}). + +\exitem{-storage-abbr-desc} An extension of the previous example +where the user needs to provide a~description. + +\exitem{-chap-hyperfirst} This document illustrates how to add +a~custom key using \cs{glsaddstoragekey} and hook into the \glslike\ +and \glstextlike\ mechanism used to determine whether or not to +hyperlink an entry. + +\exitem{-font-abbr} This document illustrates how to different fonts +for abbreviations within the style. + +\exitem{-numberlist} This document illustrates how to reference the +\gls{numberlist} in the document text. This requires an additional +\LaTeX\ run: +\begin{prompt} +latex sample-numberlist +makeglossaries sample-numberlist +latex sample-numberlist +latex sample-numberlist +\end{prompt} + +\exitem{People} This document illustrates how you can hook into the +standard sort mechanism to adjust the way the sort key is set. This +requires an additional run to ensure the table of contents is +up-to-date: +\begin{prompt} +latex samplePeople +makeglossaries samplePeople +latex samplePeople +latex samplePeople +\end{prompt} + +\exitem{Sort} This is another document that illustrates how to hook +into the standard sort mechanism. An additional run is required to +ensure the table of contents is up-to-date: +\begin{prompt} +latex sampleSort +makeglossaries sampleSort +latex sampleSort +latex sampleSort +\end{prompt} + +\exitem{-nomathhyper} This document illustrates how to selectively +enable and disable entry hyperlinks in \ics{glsentryfmt}. + +\exitem{-entryfmt} This document illustrates how to change the +way an entry is displayed in the text. + +\exitem{-prefix} This document illustrates the use of the +\sty{glossaries-prefix} package. An additional run is required to +ensure the table of contents is up-to-date: +\begin{prompt} +latex sample-prefix +makeglossaries sample-prefix +latex sample-prefix +latex sample-prefix +\end{prompt} + +\exitem{accsupp} This document +uses the experimental \sty{glossaries-accsupp} package. The +symbol is set to the replacement text. Note that some PDF +viewers don't use the accessibility support. Information +about the \styfmt{glossaries-accsupp} package can be found in +\sectionref{sec:accsupp}. + +\exitem{-ignored} This document defines an ignored glossary for +common terms that don't need a definition. + +\exitem{-entrycount} This document uses \ics{glsenableentrycount} +and \ics{cgls} (described in \sectionref{sec:enableentrycount}) +so that acronyms only used once don't appear in the list of +acronyms. +\end{samplelist} + +\section{Dummy Entries for Testing} +\label{sec:lipsum} + +In addition to the sample files described above, \sty{glossaries} also provides +some files containing lorum ipsum dummy entries. These are provided +for testing purposes and are on \TeX's path (in +\texttt{tex\slash latex\slash glossaries\slash test-entries}) so they can be included +via \ics{input} or \ics{loadglsentries}. The files are as follows: +\begin{description} +\item[example-glossaries-brief.tex] These entries all have brief +descriptions. For example: +\begin{verbatim} +\newglossaryentry{lorem}{name={lorem},description={ipsum}} +\end{verbatim} + +\item[example-glossaries-long.tex] These entries all have long +descriptions. For example: +\begin{verbatim} +\newglossaryentry{loremipsum}{name={lorem ipsum}, +description={dolor sit amet, consectetuer adipiscing +elit. Ut purus elit, vestibulum ut, placerat ac, +adipiscing vitae, felis. Curabitur dictum gravida +mauris.}} +\end{verbatim} + +\item[example-glossaries-multipar.tex] These entries all have +multi-paragraph descriptions. + +\item[example-glossaries-symbols.tex] These entries all use the +\gloskey{symbol} key. For example: +\begin{verbatim} +\newglossaryentry{alpha}{name={alpha}, +symbol={\ensuremath{\alpha}}, +description={Quisque ullamcorper placerat ipsum.}} +\end{verbatim} + +\item[example-glossaries-symbolnames.tex] Similar to the previous +file but the \gloskey{symbol} key isn't used. Instead the symbol +is stored in the \gloskey{name} key. For example: +\begin{verbatim} +\newglossaryentry{sym.alpha}{sort={alpha}, +name={\ensuremath{\alpha}}, +description={Quisque ullamcorper placerat ipsum.}} +\end{verbatim} + +\item[example-glossaries-images.tex] These entries use the +\gloskey{user1} key to store the name of an image file. (The images +are provided by the \sty{mwe} package and should be on \TeX's path.) +One entry doesn't have an associated image to help test for a~missing key. + +\item[example-glossaries-acronym.tex] These entries are all +abbreviations. For example: +\begin{verbatim} +\newacronym[type=\glsdefaulttype]{lid}{LID}{lorem ipsum +dolor} +\end{verbatim} + +\item[example-glossaries-acronym-desc.tex] These entries are all +abbreviations that use the \gloskey{description} key. +For example: +\begin{verbatim} +\newacronym[type=\glsdefaulttype, + description={fringilla a, euismod sodales, + sollicitudin vel, wisi}]{ndl}{NDL}{nam dui ligula} +\end{verbatim} + +\item[example-glossaries-acronyms-lang.tex] These entries are all +abbreviations, where some of them have a~translation supplied in the +\gloskey{user1} key. +For example: +\begin{verbatim} +\newacronym[type=\glsdefaulttype,user1={love itself}] + {li}{LI}{lorem ipsum} +\end{verbatim} + +\item[example-glossaries-parent.tex] These are hierarchical entries +where the child entries use the \gloskey{name} key. +For example: +\begin{verbatim} +\newglossaryentry{sedmattis}{name={sed mattis}, +description={erat sit amet} + +\newglossaryentry{gravida}{parent={sedmattis}, + name={gravida},description={malesuada}} +\end{verbatim} + +\item[example-glossaries-childnoname.tex] These are hierarchical entries +where the child entries don't use the \gloskey{name} key. +For example: +\begin{verbatim} +\newglossaryentry{scelerisque}{name={scelerisque}, + description={at}} +\end{verbatim} + +\item[example-glossaries-cite.tex] These entries use the +\gloskey{user1} key to store a citation key (or comma-separated list +of citation keys). The citations are defined in \texttt{xampl.bib}, +which should be available on all modern \TeX\ distributions. +One entry doesn't have an associated citation to help test for a~missing +key. +For example: +\begin{verbatim} +\newglossaryentry{fusce}{name={fusce}, +description={suscipit cursus sem},user1={article-minimal}} +\end{verbatim} + +\item[example-glossaries-url.tex] These entries use the +\gloskey{user1} key to store an URL associated with the entry. +For example: +\begin{verbatim} +\newglossaryentry{aenean-url}{name={aenean}, + description={adipiscing auctor est}, + user1={http://uk.tug.org/}} +\end{verbatim} +\end{description} + +The sample file \texttt{glossary-lipsum-examples.tex} in the +\texttt{doc\slash latex\slash glossaries\slash samples} directory +uses all these files. See also +\url{http://www.dickimaw-books.com/gallery/#glossaries}. +The \sty{glossaries-extra} package provides additional test files. + +\section{Multi-Lingual Support} +\label{sec:languages} + +As from version 1.17, the \styfmt{glossaries} package can be +used with \gls{xindy} as well as \gls{makeindex}. If you +are writing in a language that uses an \gls{exlatinalph} or +\gls{nonlatinalph} it's best to use \opt3 (\gls*{xindy}) +or \opt4 (\gls{bib2gls}) +as \gls*{makeindex} (\opt2) is hard-coded for the non-extended +\gls{latinalph} and \opt1 can performed limited ASCII comparisons. + +This means that with \optsor34 you are not restricted to the A, +\ldots, Z letter groups. If you want to use \gls*{xindy}, remember +to use the \pkgopt{xindy} package option. For example: +\begin{verbatim} +\documentclass[frenchb]{article} +\usepackage[utf8]{inputenc} +\usepackage[T1]{fontenc} +\usepackage{babel} +\usepackage[xindy]{glossaries} +\end{verbatim} +If you want to use \gls*{bib2gls}, you need to use the +\pkgopt{record} option with \sty{glossaries-extra} and supply the +definitions in \texttt{.bib} files. (See the \gls{bib2gls} user +manual for further details.) + +\begin{important} +Note that although a~\gls{nonlatinchar}, such as \'e, looks like a plain +character in your \filetype{.tex} file, with standard \LaTeX\ it's actually a~macro and can therefore +cause expansion problems. You may need to switch off the field +expansions with \cs{glsnoexpandfields}. This issue doesn't occur +with \XeLaTeX\ or Lua\LaTeX. +\end{important} + +With \sty{inputenc}, if you use a~\gls{nonlatinchar} (or other expandable) +character at the start of an entry name, you must place it in a group, +or it will cause a problem for commands that convert the first letter +to upper case (e.g.\ \ics{Gls}). For example: +\begin{alltt} +\verb|\newglossaryentry}{elite}{name={{|\'e\verb|}lite},| +description=\verb|{select group or class}}| +\end{alltt} +(With newer versions of \sty{mfirstuc} and \sty{datatool-base} you +may be able to omit this grouping.) +For further details, see the \qt{UTF-8} section in the +\sty{mfirstuc} user manual. + +If you are using \gls{xindy} or \gls{bib2gls}, the application needs +to know the encoding of the \filetype{.tex} file. This information +is added to the \filetype{.aux} file and can be picked up by +\gls{makeglossaries} and \gls{bib2gls}. If you use +\gls{xindy} explicitly instead of via \gls*{makeglossaries}, +you may need to specify the encoding using the \xdyopt{C} +option. Read the \gls*{xindy} manual for further details of this +option. + +As from v4.24, if you are writing in German (for example, using the \sty{ngerman} +package\footnote{deprecated, use \styfmt{babel} instead} or \sty{babel} with the \pkgopt{ngerman} package option), +and you want to use \gls{makeindex}['s] \mkidxopt{g} option, you'll +need to change \gls{makeindex}['s] quote character using: +\begin{definition}[\DescribeMacro\GlsSetQuote] +\cs{GlsSetQuote}\marg{character} +\end{definition} +Note that \meta{character} may not be one of \verb"?" (question +mark), \verb"|" (pipe) or \verb"!" (exclamation mark). +For example: +\begin{verbatim} +\GlsSetQuote{+} +\end{verbatim} +This must be done before \ics{makeglossaries} and any entry +definitions. It's only applicable for \app{makeindex}. This option +in conjunction with \sty{ngerman} will also cause +\app{makeglossaries} to use the \mkidxopt{g} switch when invoking +\app{makeindex}. + +\begin{important} +Be careful of \sty{babel}'s shorthands. These aren't switched +on until the start of the document, so any entries defined +in the preamble won't be able to use those shorthands. +However, if you define the entries in the document and any +of those shorthands happen to be special characters for +\gls{makeindex} or \gls{xindy} (such as the double-quote) +then this will interfere with code that tries to escape +any of those characters that occur in the \gloskey{sort} key. +\end{important} + +In general, it's best not to use \sty{babel}'s shorthands +in entry definitions. For example: +\begin{verbatim} +\documentclass{article} + +\usepackage[ngerman]{babel} +\usepackage{glossaries} + +\GlsSetQuote{+} + +\makeglossaries + +\newglossaryentry{rna}{name={ribonukleins\"aure}, + sort={ribonukleins"aure}, + description={eine Nukleins\"aure}} + +\begin{document} +\gls{rna} + +\printglossaries +\end{document} +\end{verbatim} + +The \sty{ngerman} package has the shorthands on in the preamble, so +they can be used if \cs{GlsSetQuote} has changed the \gls{makeindex} +quote character. Example: +\begin{verbatim} +\documentclass{article} + +\usepackage[ngerman]{babel} +\usepackage{glossaries} + +\GlsSetQuote{+} + +\makeglossaries + +\newglossaryentry{rna}{name={ribonukleins"aure}, + description={eine Nukleins"aure}} + +\begin{document} +\gls{rna} + +\printglossaries +\end{document} +\end{verbatim} + +\subsection{Changing the Fixed Names} +\label{sec:fixednames} + +The fixed names are produced using the commands listed in +\tableref{tab:predefinednames}. If you aren't using a language +package such as \sty{babel} or \sty{polyglossia} that uses caption +hooks, you can just redefine these commands as appropriate. If you +are using \sty{babel} or \sty{polyglossia}, you need to use their +caption hooks to change the defaults. See \urlref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}{changing +the words babel uses} or read the \sty{babel} or \sty{polyglossia} +documentation. If you have loaded \sty{babel}, then \sty{glossaries} +will attempt to load \sty{translator}, unless you have used the +\pkgopt{notranslate}, \pkgopt[false]{translate} or \pkgopt[babel]{translate} +package options. If the \sty{translator} package is loaded, the +translations are provided by dictionary files (for example, +\texttt{glossaries-dictionary-English.dict}). See the +\sty{translator} package for advice on changing translations provided by +\sty{translator} dictionaries. If you can't work out how to modify +these dictionary definitions, try switching to \sty{babel}'s +interface using \pkgopt[babel]{translate}: +\begin{verbatim} +\documentclass[english,french]{article} +\usepackage{babel} +\usepackage[translate=babel]{glossaries} +\end{verbatim} +and then use \sty{babel}'s caption hook mechanism. Note that if you +pass the language options directly to \sty{babel} rather that using +the document class options or otherwise passing the same options to +\sty{translator}, then \sty{translator} won't pick up the +language and no dictionaries will be loaded and \sty{babel}'s +caption hooks will be used instead. + +\begin{table}[htbp] +\caption{Customised Text} +\label{tab:predefinednames} +\centering +\setlength{\tabcolsep}{3pt} +\begin{tabular}{@{}l>{\raggedright}p{0.3\linewidth}>{\raggedright}p{0.4\linewidth}@{}} +\bfseries Command Name & \bfseries Translator Key Word & +\bfseries Purpose\cr +\ics{glossaryname} & \texttt{Glossary} & Title of the main glossary.\cr +\ics{acronymname} & \texttt{Acronyms} & Title of the list of acronyms +(when used with package option \pkgopt{acronym}).\cr +\ics{entryname} & \texttt{Notation (glossaries)} & +Header for first column in the glossary (for 2, 3 or 4 column glossaries +that support headers).\cr +\ics{descriptionname} & \texttt{Description (glossaries)} & +Header for second column in the glossary (for 2, 3 or 4 column glossaries +that support headers).\cr +\ics{symbolname} & \texttt{Symbol (glossaries)} & Header for symbol +column in the glossary for glossary styles that support this option.\cr +\ics{pagelistname} & \texttt{Page List (glossaries)} & +Header for page list column in the glossary for glossaries that support +this option.\cr +\ics{glssymbolsgroupname} & \texttt{Symbols (glossaries)} & +Header for symbols section of the glossary for glossary styles that +support this option.\cr +\ics{glsnumbersgroupname} & \texttt{Numbers (glossaries)} & Header for +numbers section of the glossary for glossary styles that support +this option. +\end{tabular} +\end{table} + +As from version 4.12, multilingual support is provided by separate +language modules that need to be installed in addition to installing +the \styfmt{glossaries} package. You only need to install the +modules for the languages that you require. If the language module +has an unmaintained status, you can volunteer to take over the +maintenance by contacting me at +\url{http://www.dickimaw-books.com/contact.html}. The +\sty{translator} dictionary files for \styfmt{glossaries} are now +provided by the appropriate language module. For further details +about information specific to a given language, please see the +documentation for that language module. + +Examples of use: +\begin{itemize} +\item Using \sty{babel} and \sty{translator}: +\begin{verbatim} +\documentclass[english,french]{article} +\usepackage{babel} +\usepackage{glossaries} +\end{verbatim} +(\sty{translator} is automatically loaded). + +\item Using \sty{babel}: +\begin{verbatim} +\documentclass[english,french]{article} +\usepackage{babel} +\usepackage[translate=babel]{glossaries} +\end{verbatim} +(\sty{translator} isn't loaded). + +\item Using \sty{polyglossia}: +\begin{verbatim} +\documentclass{article} +\usepackage{polyglossia} +\setmainlanguage{english} +\usepackage{glossaries} +\end{verbatim} + +\end{itemize} + +Due to the varied nature of glossaries, it's likely that the +predefined translations may not be appropriate. If you are using the +\sty{babel} package and the \styfmt{glossaries} package option \pkgopt[babel]{translate}, you need to be familiar with the advice given in +\urlref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}{changing +the words babel uses}. If you are using the \sty{translator} +package, then you can provide your own dictionary with the necessary +modifications (using \cs{deftranslation}) and load it using +\cs{usedictionary}. If you simply want to change the title of a +glossary, you can use the \gloskey[printglossary]{title} key in +commands like \cs{printglossary} (but not the iterative commands +like \cs{printglossaries}). + +\begin{important} +Note that the \sty{translator} dictionaries are loaded at the beginning of the +document, so it won't have any effect if you put \cs{deftranslation} +in the preamble. It should be put in your personal dictionary +instead (as in the example below). See the \sty{translator} +documentation for further details. (Now with \sty{beamer} +documentation.) +\end{important} + +Your custom dictionary doesn't have to be just a translation from +English to another language. You may prefer to have a dictionary for +a particular type of document. For example, suppose your +institution's in-house reports have to have the glossary labelled as +\qt{Nomenclature} and the page list should be labelled +\qt{Location}, then you can create a file called, say, +\begin{verbatim} +myinstitute-glossaries-dictionary-English.dict +\end{verbatim} +that contains the following: +\begin{verbatim} +\ProvidesDictionary{myinstitute-glossaries-dictionary}{English} +\deftranslation{Glossary}{Nomenclature} +\deftranslation{Page List (glossaries)}{Location} +\end{verbatim} +You can now load it using: +\begin{verbatim} +\usedictionary{myinstitute-glossaries-dictionary} +\end{verbatim} +(Make sure that \texttt{myinstitute-glossaries-dictionary-English.dict} +can be found by \TeX.) If you want to share your custom dictionary, +you can upload it to \href{http://www.ctan.org/}{CTAN}. + +If you are using \sty{babel} and don't want to use the +\sty{translator} interface, you can use the package +option \pkgopt[babel]{translate}. For example: +\begin{verbatim} +\documentclass[british]{article} + +\usepackage{babel} +\usepackage[translate=babel]{glossaries} + +\addto\captionsbritish{% + \renewcommand*{\glossaryname}{List of Terms}% + \renewcommand*{\acronymname}{List of Acronyms}% +} +\end{verbatim} + +Note that \gls{xindy} and \gls{bib2gls} provide much better multi-lingual support +than \gls{makeindex}, so I~recommend that you use \optsor34 +if you have glossary entries that contain +\glspl{nonlatinchar}. See \sectionref{sec:xindy} for further +details on \gls{xindy}, and see the \gls{bib2gls} user manual for +further details of that application. + +\subsubsection{Creating a New Language Module} +\label{sec:newlang} + +The \styfmt{glossaries} package now uses the \sty{tracklang} package +to determine which language modules need to be loaded. If you want +to create a new language module, you should first read the +\sty{tracklang} documentation. + +To create a new language module, you need to at least create two +files: \texttt{glossaries-}\meta{lang}\texttt{.ldf} and +\texttt{glossaries-dictionary-}\meta{Lang}\texttt{.dict} where +\meta{lang} is the root language name (for example, +\texttt{english}) and \meta{Lang} is the language name used by +\sty{translator} (for example, \texttt{English}). + +Here's an example of \texttt{glossaries-dictionary-English.dict}: +\begin{verbatim} +\ProvidesDictionary{glossaries-dictionary}{English} + +\providetranslation{Glossary}{Glossary} +\providetranslation{Acronyms}{Acronyms} +\providetranslation{Notation (glossaries)}{Notation} +\providetranslation{Description (glossaries)}{Description} +\providetranslation{Symbol (glossaries)}{Symbol} +\providetranslation{Page List (glossaries)}{Page List} +\providetranslation{Symbols (glossaries)}{Symbols} +\providetranslation{Numbers (glossaries)}{Numbers} +\end{verbatim} +You can use this as a template for your dictionary file. Change +\texttt{English} to the \sty{translator} name for your language +(so that it matches the file name +\texttt{glossaries-dictionary-}\meta{Lang}\texttt{.dict}) +and, for each \cs{providetranslation}, change the second argument to +the appropriate translation. + +Here's an example of \texttt{glossaries-english.ldf}: +\begin{verbatim} +\ProvidesGlossariesLang{english} + +\glsifusedtranslatordict{English} +{% + \addglossarytocaptions{\CurrentTrackedLanguage}% + \addglossarytocaptions{\CurrentTrackedDialect}% +} +{% + \@ifpackageloaded{polyglossia}% + {% + \newcommand*{\glossariescaptionsenglish}{% + \renewcommand*{\glossaryname}{\textenglish{Glossary}}% + \renewcommand*{\acronymname}{\textenglish{Acronyms}}% + \renewcommand*{\entryname}{\textenglish{Notation}}% + \renewcommand*{\descriptionname}{\textenglish{Description}}% + \renewcommand*{\symbolname}{\textenglish{Symbol}}% + \renewcommand*{\pagelistname}{\textenglish{Page List}}% + \renewcommand*{\glssymbolsgroupname}{\textenglish{Symbols}}% + \renewcommand*{\glsnumbersgroupname}{\textenglish{Numbers}}% + }% + }% + {% + \newcommand*{\glossariescaptionsenglish}{% + \renewcommand*{\glossaryname}{Glossary}% + \renewcommand*{\acronymname}{Acronyms}% + \renewcommand*{\entryname}{Notation}% + \renewcommand*{\descriptionname}{Description}% + \renewcommand*{\symbolname}{Symbol}% + \renewcommand*{\pagelistname}{Page List}% + \renewcommand*{\glssymbolsgroupname}{Symbols}% + \renewcommand*{\glsnumbersgroupname}{Numbers}% + }% + }% + \ifcsdef{captions\CurrentTrackedDialect} + {% + \csappto{captions\CurrentTrackedDialect}% + {% + \glossariescaptionsenglish + }% + }% + {% + \ifcsdef{captions\CurrentTrackedLanguage} + { + \csappto{captions\CurrentTrackedLanguage}% + {% + \glossariescaptionsenglish + }% + }% + {% + }% + }% + \glossariescaptionsenglish +} +\renewcommand*{\glspluralsuffix}{s} +\renewcommand*{\glsacrpluralsuffix}{\glspluralsuffix} +\renewcommand*{\glsupacrpluralsuffix}{\glstextup{\glspluralsuffix}} +\end{verbatim} +This is a somewhat longer file, but again you can use it as a +template. Replace \texttt{English} with the \sty{translator} +language label \meta{Lang} used for the dictionary file and +replace \texttt{english} with the root language name \meta{lang}. Within the +definition of \cs{glossariescaptions}\meta{lang}, replace the +English text (such as \qt{Glossaries}) with the appropriate +translation. + +\label{pluralsuffix}% +\textbf{Note:} the suffixes used to generate the plural forms when +the plural hasn't been specified are given by +\cs{glspluralsuffix} (for general entries) and +\cs{glsupacrpluralsuffix} for acronyms where the suffix needs to be +set using \cs{glstextup} to counteract the effects of \cs{textsc} +and \cs{glsacrpluralsuffix} for other acronym styles. There's no +guarantee when these commands will be expanded. They may be expanded +on definition or they may be expanded on use, depending on the +\styfmt{glossaries} configuration. + +\begin{important} +Therefore these plural suffix command definitions +aren't included in the caption mechanism as that's typically not switched on +until the start of the document. \textbf{This means that the suffix in +effect will be for the last loaded language that redefined these +commands.} It's best to initialise these commands to the most common +suffix required in your document and use the \gloskey{plural}, +\gloskey{longplural}, \gloskey{shortplural} etc keys to override +exceptions. +\end{important} + +If you want to add a regional variation, create a file called +\texttt{glossaries-}\meta{iso lang}\texttt{-}\meta{iso +country}\texttt{.ldf}, where \meta{iso lang} is the ISO language +code and \meta{iso country} is the ISO country code. For example, +\texttt{glossaries-en-GB.ldf}. This file can load the root +language file and make the appropriate changes, for example: +\begin{verbatim} + \ProvidesGlossariesLang{en-GB} + \RequireGlossariesLang{english} + \glsifusedtranslatordict{British} + {% + \addglossarytocaptions{\CurrentTrackedLanguage}% + \addglossarytocaptions{\CurrentTrackedDialect}% + } + {% + \@ifpackageloaded{polyglossia}% + {% + % Modify \glossariescaptionsenglish as appropriate for + % polyglossia + }% + {% + % Modify \glossariescaptionsenglish as appropriate for + % non-polyglossia + }% + } +\end{verbatim} + +If the translations includes \glspl{nonlatinchar}, it's necessary to +provide code that's independent of the input encoding. Remember that +while some users may use UTF-8, others may use Latin-1 or any other +supported encoding, but while users won't appreciate you enforcing +your preference on them, it's useful to provide a UTF-8 version for +\XeLaTeX\ users. + +The \texttt{glossaries-irish.ldf} file provides this as follows: +\begin{verbatim} +\ProvidesGlossariesLang{irish} + +\glsifusedtranslatordict{Irish} +{% + \addglossarytocaptions{\CurrentTrackedLanguage}% + \addglossarytocaptions{\CurrentTrackedDialect}% +} +{% + \ifdefstring{\inputencodingname}{utf8} + {\input{glossaries-irish-utf8.ldf}}% + {% + \ifdef{\XeTeXinputencoding}% XeTeX defaults to UTF-8 + {\input{glossaries-irish-utf8.ldf}}% + {\input{glossaries-irish-noenc.ldf}} + } + \ifcsdef{captions\CurrentTrackedDialect} + {% + \csappto{captions\CurrentTrackedDialect}% + {% + \glossariescaptionsirish + }% + }% + {% + \ifcsdef{captions\CurrentTrackedLanguage} + { + \csappto{captions\CurrentTrackedLanguage}% + {% + \glossariescaptionsirish + }% + }% + {% + }% + }% + \glossariescaptionsirish +} +\end{verbatim} +(Again you can use this as a template. Replace \texttt{irish} with +your root language label and \texttt{Irish} with the +\sty{translator} dictionary label.) + +There are now two extra files: \texttt{glossaries-irish-noenc.ldf} +and \texttt{glossaries-irish-utf8.ldf}. + +These both define \cs{glossariescaptionsirish} but the \texttt{*-noenc.ldf} uses +\LaTeX\ accent commands: +\begin{verbatim} +\@ifpackageloaded{polyglossia}% +{% + \newcommand*{\glossariescaptionsirish}{% + \renewcommand*{\glossaryname}{\textirish{Gluais}}% + \renewcommand*{\acronymname}{\textirish{Acrainmneacha}}% + \renewcommand*{\entryname}{\textirish{Ciall}}% + \renewcommand*{\descriptionname}{\textirish{Tuairisc}}% + \renewcommand*{\symbolname}{\textirish{Comhartha}}% + \renewcommand*{\glssymbolsgroupname}{\textirish{Comhartha\'{\i}}}% + \renewcommand*{\pagelistname}{\textirish{Leathanaigh}}% + \renewcommand*{\glsnumbersgroupname}{\textirish{Uimhreacha}}% + }% +}% +{% + \newcommand*{\glossariescaptionsirish}{% + \renewcommand*{\glossaryname}{Gluais}% + \renewcommand*{\acronymname}{Acrainmneacha}% + \renewcommand*{\entryname}{Ciall}% + \renewcommand*{\descriptionname}{Tuairisc}% + \renewcommand*{\symbolname}{Comhartha}% + \renewcommand*{\glssymbolsgroupname}{Comhartha\'{\i}}% + \renewcommand*{\pagelistname}{Leathanaigh}% + \renewcommand*{\glsnumbersgroupname}{Uimhreacha}% + }% +} +\end{verbatim} +whereas the \texttt{*-utf8.ldf} replaces the accent commands with +the appropriate UTF-8 characters. + + +\section{Generating the Associated Glossary Files} +\label{sec:makeglossaries} + +\begin{important} +This section is only applicable if you have chosen \optsor23. You can +ignore this section if you have chosen any of the other options. If you want to +alphabetically sort your entries always remember to use the +\gloskey{sort} key if the \gloskey{name} contains any \LaTeX\ commands. +\end{important} + +If this section seriously confuses you, and you can't work out how +to run external tools like \gls{makeglossaries} or \gls{makeindex}, you can try using +the \pkgopt{automake} package option, described in +\sectionref{sec:pkgopts-sort}, but you will need \TeX's shell escape +enabled. + +In order to generate a sorted glossary with compact +\glspl{numberlist}, it is necessary to use an external +\gls{indexingapp} as an intermediate step (unless you have chosen +\opt1, which uses \TeX\ to do the sorting or \opt5, which doesn't +perform any sorting). It is this application +that creates the file containing the code required to typeset the +glossary. \textbf{If this step is omitted, the glossaries will not +appear in your document.} The two \glspl*{indexingapp} that are most +commonly used with \LaTeX\ are \gls{makeindex} and \gls{xindy}. As +from version 1.17, the \styfmt{glossaries} package can be used with +either of these applications. Previous versions were designed to be +used with \gls*{makeindex} only. With the \sty{glossaries-extra} package, you +can also use \gls{bib2gls} as the indexing application. (See +the \sty{glossaries-extra} and \gls{bib2gls} user manuals for +further details.) Note that \gls*{xindy} and \gls*{bib2gls} have much +better multi-lingual support than \gls*{makeindex}, so \gls*{xindy} +or \gls*{bib2gls} are recommended if you're not writing in English. +Commands that only have an effect when \gls*{xindy} is used are +described in \sectionref{sec:xindy}. + +\begin{important} +This is a multi-stage process, but there are methods of automating +document compilation using applications such as \app{latexmk} and +\app{arara}. With \app{arara} you can just add special comments to +your document source: +\begin{alltt} +\% arara: pdflatex +\% arara: makeglossaries +\% arara: pdflatex +\end{alltt} +With \app{latexmk} you need to set up the required dependencies. +\end{important} + +The \styfmt{glossaries} package comes with the Perl script +\gls{makeglossaries} which will run \gls{makeindex} or \gls{xindy} +on all the glossary files using a customized style file (which is +created by \ics{makeglossaries}). See +\sectionref{sec:makeglossariesapp} for further +details. Perl is stable, cross-platform, open source software that +is used by a number of \TeX-related applications (including +\gls*{xindy} and \app{latexmk}). Most Unix-like +operating systems come with a~Perl interpreter. \TeX~Live also comes +with a~Perl interpreter. MiK\TeX\ doesn't come with a~Perl +interpreter so if you are a~Windows MiK\TeX\ user you will need to +install Perl if you want to use \gls{makeglossaries} or \gls{xindy}. +Further information is available at \url{http://www.perl.org/about.html} +and +\href{http://tex.stackexchange.com/questions/158796/miktex-and-perl-scripts-and-one-python-script}{MiKTeX and Perl scripts (and one Python script)}. + +The advantages of using \gls*{makeglossaries}: +\begin{itemize} +\item It automatically detects whether to use \gls*{makeindex} or +\gls*{xindy} and sets the relevant application switches. + +\item One call of \gls*{makeglossaries} will run +\gls*{makeindex}\slash\gls*{xindy} for each glossary type. + +\item If things go wrong, \gls{makeglossaries} will scan the +messages from \gls{makeindex} or \gls{xindy} and attempt to diagnose +the problem in relation to the \styfmt{glossaries} package. This +will hopefully provide more helpful messages in some cases. If it +can't diagnose the problem, you will have to read the relevant transcript +file and see if you can work it out from the \gls*{makeindex} or +\gls*{xindy} messages. + +\item If \gls{makeindex} warns about multiple encap values, +\gls{makeglossaries} will detect this and attempt to correct the +problem.\footnote{Added to version \gls{makeglossaries} 2.18.} This +correction is only provided by \gls{makeglossaries} when +\gls{makeindex} is used since \gls{xindy} uses the order of the +attributes list to determine which format should take precedence. +(See \cs{GlsAddXdyAttribute} in \sectionref{sec:xindyloc}.) + +\end{itemize} + +As from version 4.16, the \styfmt{glossaries} package also comes +with a~Lua script called \gls{makeglossaries-lite.lua}. This is a +\emph{trimmed-down} alternative to the \gls{makeglossaries} Perl +script. It doesn't have some of the options that the Perl version +has and it doesn't attempt to diagnose any problems, but since +modern \TeX\ distributions come with Lua\TeX\ (and therefore have +a~Lua interpreter) you don't need to install anything else in order +to use \gls{makeglossaries-lite.lua} so it's an alternative to +\gls{makeglossaries} if you want to use \opt2 (\gls{makeindex}). + +If things go wrong and you can't work out why your glossaries +aren't being generated correctly, you can use +\gls{makeglossariesgui} as a diagnostic tool. Once you've +fixed the problem, you can then go back to using +\gls{makeglossaries} or \gls{makeglossaries-lite.lua}. + +Whilst I strongly recommended that you use the \gls{makeglossaries} +Perl script or the \gls{makeglossaries-lite.lua} Lua script, it is +possible to use the \styfmt{glossaries} package without using those +applications. However, note that some commands and package options +have no effect if you explicitly run \gls{makeindex}\slash\gls{xindy}. +These are listed in \tableref{tab:makeglossariesCmds}. + +\begin{important} +If you are choosing not to use \gls*{makeglossaries} because you +don't want to install Perl, you will only be able to use +\gls*{makeindex} as \gls*{xindy} also requires Perl. (Other useful +Perl scripts include \appfmt{epstopdf} and \appfmt{latexmk}, so it's +well-worth the effort to install Perl.) +\end{important} + +Note that if any of your entries use an entry +that is not referenced outside the glossary, you will need to +do an additional \gls{makeglossaries}, \gls{makeindex} +or \gls{xindy} run, as appropriate. For example, +suppose you have defined the following entries:\footnote{As from +v3.01 \ics{gls} is no longer fragile and doesn't need protecting.} +\begin{verbatim} +\newglossaryentry{citrusfruit}{name={citrus fruit}, +description={fruit of any citrus tree. (See also +\gls{orange})}} + +\newglossaryentry{orange}{name={orange}, +description={an orange coloured fruit.}} +\end{verbatim} +and suppose you have \verb|\gls{citrusfruit}| in your document +but don't reference the \texttt{orange} entry, then the +\texttt{orange} entry won't appear in your glossary until +you first create the glossary and then do another run +of \gls{makeglossaries}, \gls{makeindex} or \gls{xindy}. +For example, if the document is called \texttt{myDoc.tex}, then +you must do: +\begin{prompt} +latex myDoc +makeglossaries myDoc +latex myDoc +makeglossaries myDoc +latex myDoc +\end{prompt} +(Note that if you use \gls{glossaries-extra}, this will be done +automatically for you if the \pkgoptfmt{indexcrossrefs} feature is +enabled. See the \gls*{glossaries-extra} user guide for further +details.) + +Likewise, an additional \gls{makeglossaries} and \LaTeX\ run +may be required if the document pages shift with re-runs. For +example, if the page numbering is not reset after the table of +contents, the insertion of the table of contents on the second +\LaTeX\ run may push glossary entries across page boundaries, which +means that the \glspl{numberlist} in the glossary may +need updating. + +The examples in this document assume that you are accessing +\gls{makeglossaries}, \gls{xindy} or \gls{makeindex} via a terminal. +Windows users can use the MSDOS Prompt which is usually accessed via +the \menu{Start}\submenu{All Programs} menu or +\menu{Start}\submenu{All Programs}\submenu{Accessories} menu. + +Alternatively, your text editor may have the facility to create a +function that will call the required application. See +\href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating +makeglossaries or makeglossaries-lite or bib2gls into the document +build}. + +If any problems occur, remember to check the transcript files +(e.g.\ \filetype{.glg} or \filetype{.alg}) for messages. + +\begin{table}[htbp] +\caption[Commands and package options that have no effect when +using xindy or makeindex explicitly]{Commands and package options that have no effect when +using \gls{xindy} or \gls{makeindex} explicitly} +\label{tab:makeglossariesCmds} +\vskip\baselineskip +\begin{tabular}{@{}lll@{}} +\bfseries Command or Package Option & \gls{makeindex} & +\gls{xindy}\\ +\pkgopt[letter]{order} & use \mkidxopt{l} & + use \xdyopt{M}\texttt{ ord/letorder}\\ +\pkgopt[word]{order} & default & default\\ +\pkgopt{xindy}=\{\pkgoptfmt{language=}\meta{lang}\pkgoptfmt{,codename=}\meta{code}\} & +N/A & use \xdyopt{L} \meta{lang} \xdyopt{C} \meta{code}\\ +\ics{GlsSetXdyLanguage}\marg{lang} & N/A & +use \xdyopt{L} \meta{lang}\\ +\ics{GlsSetXdyCodePage}\marg{code} & N/A & +use \xdyopt{C} \meta{code} +\end{tabular} +\par +\end{table} + + +\subsection{Using the makeglossaries Perl Script} +\label{sec:makeglossariesapp} + +The \gls{makeglossaries} script picks up the relevant information +from the auxiliary (\filetype{.aux}) file and will either call +\gls{xindy} or \gls{makeindex}, depending on the supplied +information. Therefore, you only need to pass the document's name +without the extension to \gls*{makeglossaries}. For example, if your +document is called \texttt{myDoc.tex}, type the following in your +terminal: +\begin{prompt} +latex myDoc +makeglossaries myDoc +latex myDoc +\end{prompt} +You may need to explicitly load \gls{makeglossaries} into Perl: +\begin{prompt} +perl makeglossaries myDoc +\end{prompt} + +Windows users: \TeX~Live on Windows has its own internal Perl +interpreter and provides \texttt{makeglossaries.exe} as a~convenient +wrapper for the \gls{makeglossaries} Perl script. MiKTeX also +provides a~wrapper \texttt{makeglossaries.exe} but doesn't provide +a~Perl interpreter, which is still required even if you run MiKTeX's +\texttt{makeglossaries.exe}, so with MiKTeX you'll need to install +Perl.\footnote{The batch file \texttt{makeglossaries.bat} has been +removed since the \TeX\ distributions for Windows provide +\texttt{makeglossaries.exe}.} There's more information about this at +\url{http://tex.stackexchange.com/q/158796/19862} on the TeX.SX +site. + +The \gls{makeglossaries} script attempts to fork the +\gls{makeindex}\slash\gls{xindy} process using \texttt{open()} on the +piped redirection \verb"2>&1 |" and parses the processor output to +help diagnose problems. If this method fails \gls{makeglossaries} +will print an \qt{Unable to fork} warning and will retry without +redirection. If you run \gls{makeglossaries} on an operating system +that doesn't support this form of redirection, then you can use the +\mkglsopt{Q} switch to suppress this warning or you can use the +\mkglsopt{k} switch to make \gls{makeglossaries} automatically use +the fallback method without attempting the redirection. Without this +redirection, the \mkglsopt{q} (quiet) switch doesn't work as well. + +You can specify in which directory the \filetype{.aux}, +\filetype{.glo} etc files are located using the \texttt{-d} switch. +For example: +\begin{prompt} +pdflatex -output-directory myTmpDir myDoc +makeglossaries -d myTmpDir myDoc +\end{prompt} +Note that \gls*{makeglossaries} assumes by default that +\gls*{makeindex}\slash\gls*{xindy} is on your operating system's +path. If this isn't the case, you can specify the full pathname +using \mkglsopt{m} \meta{path/to/makeindex} for \gls*{makeindex} +or \mkglsopt{x} \meta{path/to/xindy} for \gls*{xindy}. + +As from \gls{makeglossaries} v2.18, if you are using +\gls{makeindex}, there's a check for \gls*{makeindex}['s] multiple +encap warning. This is where different encap values (location formats) are +used on the same location for the same entry. For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} +\makeglossaries + +\newglossaryentry{sample}{name={sample},description={an example}} + +\begin{document} +\gls{sample}, \gls[format=textbf]{sample}. +\printglossaries +\end{document} +\end{verbatim} +If you explicitly use \gls{makeindex}, this will cause a warning and +the location list will be \qt{1, \textbf{1}}. That is, the page +number will be repeated with each format. As from v2.18, +\gls{makeglossaries} will check for this warning and, if found, will +attempt to correct the problem by removing duplicate locations and +retrying. There's no similar check for \gls{xindy} as \gls*{xindy} +won't produce any warning and will simply discard duplicates. + +The \gls{makeglossaries} script contains POD (Plain Old +Documentation). If you want, you can create a man page for +\gls*{makeglossaries} using \app{pod2man} and move the +resulting file onto the man path. Alternatively do +\texttt{makeglossaries -{}-help} for a list of all options or +\texttt{makeglossaries -{}-version} for the version number. + +\begin{important} +When upgrading the \styfmt{glossaries} package, make sure you also +upgrade your version of \gls{makeglossaries}. The current version is +4.41. +\end{important} + +\subsection{Using the makeglossaries-lite Lua Script} +\label{sec:makeglossarieslua} + +The Lua alternative to the \gls{makeglossaries} Perl script requires +a~Lua interpreter, which should already be available if you have +a~modern \TeX\ distribution that includes Lua\TeX. Lua is +a~light-weight, cross-platform scripting language, but because it's +light-weight it doesn't have the full-functionality of heavy-weight +scripting languages, such as Perl. The \gls{makeglossaries-lite.lua} +script is therefore limited by this and some of the options +available to the \gls{makeglossaries} Perl script aren't available +here. (In particular the \mkglsopt{d} option.) + +\begin{important} +Note that \TeX~Live on Unix-like systems creates a +symbolic link called \texttt{makeglossaries-lite} (without the +\texttt{.lua} extension) to the actual +\texttt{makeglossaries-lite.lua} script, so you may not need to +supply the extension. +\end{important} + +The \gls{makeglossaries-lite.lua} script can be invoked in the same way +as \gls{makeglossaries}. For example, if your document is called +\texttt{myDoc.tex}, then do +\begin{prompt} +makeglossaries-lite.lua myDoc +\end{prompt} +or +\begin{prompt} +makeglossaries-lite myDoc +\end{prompt} + +\emph{Some} of the options available with \gls{makeglossaries} are +also available with \gls{makeglossaries-lite.lua}. For a complete list of +available options, do +\begin{prompt} +makeglossaries-lite.lua -{}-help +\end{prompt} + + +\subsection[Using xindy explicitly (Option~3)]{Using +\gls{xindy} explicitly (\ifpdf \opt3\else Option 3\fi)} +\label{sec:xindyapp} + +\Gls{xindy} comes with \TeX~Live. It has also been added +to Mik\TeX, but if you don't have it installed, see +\href{http://tex.stackexchange.com/questions/71167/how-to-use-xindy-with-miktex}{How +to use Xindy with MikTeX} on +\urlfootref{http://www.stackexchange.com/}{\TeX\ on StackExchange}. + +If you want to use \gls{xindy} to process the glossary +files, you must make sure you have used the +\pkgopt{xindy} package option: +\begin{verbatim} +\usepackage[xindy]{glossaries} +\end{verbatim} +This is required regardless of whether you use \gls{xindy} +explicitly or whether it's called implicitly via applications such +as \gls{makeglossaries}. This causes the glossary +entries to be written in raw \gls*{xindy} format, so you need to +use \xdyopt{I}\texttt{ xindy} \emph{not} \xdyopt{I}\texttt{ tex}. + +To run \gls{xindy} type the following in your terminal +(all on one line): +\begin{prompt} +xindy -L \meta{language} -C \meta{encoding} -I xindy -M \meta{style} -t \meta{base}.glg -o \meta{base}.gls \meta{base}.glo +\end{prompt} +where \meta{language} is the required language name, \meta{encoding} +is the encoding, \meta{base} is the name of the document without the +\filetype{.tex} extension and \meta{style} is the name of the +\gls{xindy} style file without the \filetype{.xdy} extension. +The default name for this style file is \meta{base}\filetype{.xdy} +but can be changed via \ics{setStyleFile}\marg{style}. You may need +to specify the full path name depending on the current working +directory. If any of the file names contain spaces, you must delimit +them using double-quotes. + +For example, if your document is called \texttt{myDoc.tex} and +you are using UTF8 encoding in English, then type the +following in your terminal: +\begin{prompt} +xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo +\end{prompt} + +Note that this just creates the main glossary. You need to do +the same for each of the other glossaries (including the +list of acronyms if you have used the \pkgopt{acronym} +package option), substituting \filetype{.glg}, \filetype{.gls} +and \filetype{.glo} with the relevant extensions. For example, +if you have used the \pkgopt{acronym} package option, then +you would need to do: +\begin{prompt} +xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.alg -o myDoc.acr myDoc.acn +\end{prompt} +For additional glossaries, the extensions are those supplied +when you created the glossary with \ics{newglossary}. + +Note that if you use \gls{makeglossaries} instead, you can +replace all those calls to \gls{xindy} with just one call +to \gls*{makeglossaries}: +\begin{prompt} +makeglossaries myDoc +\end{prompt} +Note also that some commands and package options have no effect if +you use \gls{xindy} explicitly instead of using +\gls*{makeglossaries}. These are listed in +\tableref{tab:makeglossariesCmds}. + + +\subsection[Using makeindex explicitly (Option~2)]{Using +\gls{makeindex} explicitly (\ifpdf \opt2\else Option 2\fi)} +\label{sec:makeindexapp} + +If you want to use \gls{makeindex} explicitly, you must +make sure that you haven't used the \pkgopt{xindy} package +option or the glossary entries will be written in the wrong +format. To run \gls*{makeindex}, type the following in +your terminal: +\begin{prompt} +makeindex -s \meta{style}.ist -t \meta{base}.glg -o \meta{base}.gls \meta{base}.glo +\end{prompt} +where \meta{base} is the name of your document without the +\filetype{.tex} extension and \meta{style}\filetype{.ist} is the +name of the \gls{makeindex} style file. By default, this is +\meta{base}\filetype{.ist}, but may be changed via +\ics{setStyleFile}\marg{style}. Note that there are other options, +such as \mkidxopt{l} (letter ordering). See the \gls*{makeindex} +manual for further details. + +For example, if your document is called \texttt{myDoc.tex}, then +type the following at the terminal: +\begin{prompt} +makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo +\end{prompt} +Note that this only creates the main glossary. If you have +additional glossaries (for example, if you have used the +\pkgopt{acronym} package option) then you must call +\gls{makeindex} for each glossary, substituting +\filetype{.glg}, \filetype{.gls} and \filetype{.glo} with the +relevant extensions. For example, if you have used the +\pkgopt{acronym} package option, then you need to type the +following in your terminal: +\begin{prompt} +makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn +\end{prompt} +For additional glossaries, the extensions are those supplied +when you created the glossary with \ics{newglossary}. + +Note that if you use \gls{makeglossaries} instead, you can +replace all those calls to \gls{makeindex} with just one call +to \gls*{makeglossaries}: +\begin{prompt} +makeglossaries myDoc +\end{prompt} +Note also that some commands and package options have no effect if +you use \gls*{makeindex} explicitly instead of using +\gls{makeglossaries}. These are listed in +\tableref{tab:makeglossariesCmds}. + + +\subsection{Note to Front-End and Script Developers} +\label{sec:notedev} + +The information needed to determine whether to use \gls{xindy} +or \gls{makeindex} and the information needed to call those +applications is stored in the auxiliary file. This information can +be gathered by a front-end, editor or script to make the glossaries +where appropriate. This section describes how the information is +stored in the auxiliary file. + +The file extensions used by each defined glossary are given by +\begin{definition}[\DescribeMacro{\@newglossary}] +\cs{@newglossary}\marg{label}\marg{log}\marg{out-ext}\marg{in-ext} +\end{definition} +where \meta{in-ext} is the extension of the +\emph{\gls{indexingapp}['s]} input file (the output file from the +\styfmt{glossaries} package's point of view), \meta{out-ext} is the +extension of the \emph{\gls*{indexingapp}['s]} output file (the +input file from the \styfmt{glossaries} package's point of view) and +\meta{log} is the extension of the \gls*{indexingapp}['s] transcript +file. The label for the glossary is also given for information +purposes only, but is not required by the \glspl*{indexingapp}. For +example, the information for the default main glossary is written +as: +\begin{verbatim} +\@newglossary{main}{glg}{gls}{glo} +\end{verbatim} + +The \gls{indexingapp}['s] style file is specified by +\begin{definition}[\DescribeMacro{\@istfilename}] +\cs{@istfilename}\marg{filename} +\end{definition} +The file extension indicates whether to use \gls{makeindex} +(\filetype{.ist}) or \gls{xindy} (\filetype{.xdy}). Note that +the glossary information is formatted differently depending on +which \gls*{indexingapp} is supposed to be used, so it's +important to call the correct one. + +Word or letter ordering is specified by: +\begin{definition}[\DescribeMacro{\@glsorder}] +\cs{@glsorder}\marg{order} +\end{definition} +where \meta{order} can be either \texttt{word} or \texttt{letter}. + +If \gls{xindy} should be used, the language and code page +for each glossary is specified by +\begin{definition}[\DescribeMacro{\@xdylanguage}\DescribeMacro{\@gls@codepage}] +\cs{@xdylanguage}\marg{label}\marg{language}\\ +\cs{@gls@codepage}\marg{label}\marg{code} +\end{definition} +where \meta{label} identifies the glossary, \meta{language} is +the root language (e.g.\ \texttt{english}) and \meta{code} +is the encoding (e.g.\ \texttt{utf8}). These commands are omitted +if \gls{makeindex} should be used. + +If \opt1 has been used, the \texttt{.aux} file will contain +\begin{definition} +\cs{@gls@reference}\marg{type}\marg{label}\marg{location} +\end{definition} +for every time an entry has been referenced. If \opt4 has been +used, the \texttt{.aux} file will contain one or more instances of +\begin{definition} +\cs{glsxtr@resource}\marg{options}\marg{basename} +\end{definition} + +\chapter{Package Options} +\label{sec:pkgopts} + +This section describes the available \styfmt{glossaries} package +options. You may omit the \texttt{=true} for boolean options. (For +example, \pkgopt{acronym} is equivalent to \pkgopt[true]{acronym}). +The \gls{glossaries-extra} package has additional options described +in the \gls*{glossaries-extra} manual. + +\begin{important} +Note that \meta{key}=\meta{value} package options can't be passed via the +document class options. (This includes options where the +\meta{value} part may be omitted, such as \pkgopt{acronym}.) This is +a general limitation not restricted to the \styfmt{glossaries} +package. Options that aren't \meta{key}=\meta{value} (such as +\pkgopt{makeindex}) may be passed via the document class options. +\end{important} + +\section{General Options} +\label{sec:pkgopts-general} + +\begin{description} +\item[\pkgoptdef{nowarn}] This suppresses all warnings generated by +the \styfmt{glossaries} package. Don't use this option if you're new to using +\styfmt{glossaries} as the warnings are designed to help detect +common mistakes (such as forgetting to use \ics{makeglossaries}). +Note that the \pkgopt[true]{debug} and \pkgopt[showtargets]{debug} will override this option. + +\item[\pkgoptdef{nolangwarn}] This suppresses the warning generated by +a missing language module. + +\item[\pkgoptdef{noredefwarn}] If you load \styfmt{glossaries} with +a~class or another package that already defines glossary related +commands, by default \styfmt{glossaries} will warn you that it's +redefining those commands. If you are aware of the consequences of +using \styfmt{glossaries} with that class or package and you don't +want to be warned about it, use this option to suppress those +warnings. Other warnings will still be issued unless you use the +\pkgopt{nowarn} option described above. + +\item[\pkgoptdef{debug}] Introduced in version 4.24. +The default setting is \pkgopt[false]{debug}. +This was a boolean option but as from v4.32 it now accepts the +values: \pkgoptfmt{false}, \pkgoptfmt{true} and +\pkgoptfmt{showtargets}. If no value is given, \pkgopt[true]{debug} is assumed. +Both \pkgopt[true]{debug} and \pkgopt[showtargets]{debug} +switch on the debug mode (and will automatically +cancel the \pkgopt{nowarn} option). The \pkgopt[showtargets]{debug} +option will additionally use +\begin{definition}[\DescribeMacro\glsshowtarget] +\cs{glsshowtarget}\marg{target name} +\end{definition} +to show the hypertarget or hyperlink name in the margin when +\cs{glsdohypertarget} is used by commands like \cs{glstarget} +and when \cs{glsdohyperlink} is used by commands like \cs{gls}. +This puts the information in the margin using \ics{marginpar} unless +math mode or inner mode are detected, in which case it puts the +information in line enclosed by square brackets. The +\gls{glossaries-extra} package provides an additional setting that +may be used to show where the indexing is occurring. See the +\gls{glossaries-extra} manual for further details. + +The purpose of the debug mode can be demonstrated with +the following example document: +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\newglossaryentry{sample1}{name={sample1}, + description={example}} +\newglossaryentry{sample2}{name={sample2}, + description={example}} +\glsadd{sample2} +\makeglossaries +\begin{document} +\gls{sample1}. +\printglossaries +\end{document} +\end{verbatim} +In this case, only the \texttt{sample1} entry has been indexed, even +though \verb|\glsadd{sample2}| appears in the source code. +This is because \verb|\glsadd{sample2}| has been used before the +associated file is opened by \ics{makeglossaries}. Since the file +isn't open yet, the information can't be written to it, which is why +the \texttt{sample2} entry doesn't appear in the glossary. + +This situation doesn't cause any errors or warnings as it's +perfectly legitimate for a user to want to use \styfmt{glossaries} +to format the entries (e.g.\ abbreviation expansion) but not display +any lists of terms, abbreviations, symbols etc. +Without \cs{makeglossaries} the indexing is suppressed but, other +than that, commands like \cs{gls} behave as usual. It's also +possible that the user may want to temporarily comment out +\cs{makeglossaries} in order to suppress the indexing while working +on a draft version to speed compilation. Therefore +\cs{makeglossaries} can't be used to enable \cs{newglossaryentry} +and \cs{glsadd}. They must be enabled by default. (It does, however, +enable the \gloskey{see} key as that's a more common problem. See +below.) + +The debug mode, enabled with the \pkgopt{debug} option, +\begin{verbatim} +\usepackage[debug]{glossaries} +\end{verbatim} +will write information to the log file when the indexing +can't occur because the associated file isn't open. +The message is written in the form +\begin{quote} +Package glossaries Info: wrglossary(\meta{type})(\meta{text}) on +input line \meta{line number}. +\end{quote} +where \meta{type} is the glossary label and \meta{text} is the line +of text that would've been written to the associated file if +it had been open. So if any entries haven't appeared in the +glossary but you're sure you used commands like \cs{glsadd} +or \cs{glsaddall}, try switching on the \pkgopt{debug} option +and see if any information has been written to the log file. + +\item[\pkgoptdef{seenoindex}] Introduced in version 4.24, this option +may take one of three values: \pkgoptfmt{error}, \pkgoptfmt{warn} or +\pkgoptfmt{ignore}. The \gloskey{see} key automatically indexes the +cross-referenced entry using \cs{glsadd}. This means that it suffers +from the same problem as the above. If used before the relevant +glossary file has been opened, the indexing can't be performed. +Since this is easy to miss, the \styfmt{glossaries} package by +default issues an error message if the \gloskey{see} key is used +before \cs{makeglossaries}. This option allows you to change the +error into just a warning (\pkgopt[warn]{seenoindex}) or +ignore it (\pkgopt[ignore]{seenoindex}) if, for example, you want +to temporarily comment out \cs{makeglossaries} to speed up the +compilation of a draft document by omitting the indexing. + +\item[\pkgoptdef{nomain}] This suppresses the creation of the main +glossary and associated \texttt{.glo} file, if unrequired. Note that +if you use this option, you must create another glossary in which to +put all your entries (either via the \pkgopt{acronym} (or +\pkgopt{acronyms}) package option described in +\sectionref{sec:pkgopts-acronym} or via the \pkgopt{symbols}, +\pkgopt{numbers} or \pkgopt{index} options described in +\sectionref{sec:pkgopts-other} or via \ics{newglossary} described in +\sectionref{sec:newglossary}). + +\begin{important} +If you don't use the main glossary and you don't use this option, +\gls{makeglossaries} will produce a warning. +\end{important} +\begin{alltt} +Warning: File '\emph{filename}.glo' is empty. +Have you used any entries defined in glossary +'main'? +Remember to use package option 'nomain' if +you don't want to use the main glossary. +\end{alltt} +If you did actually want to use the main glossary and you see this +warning, check that you have referenced the entries in that glossary +via commands such as \ics{gls}. + +\item[\pkgoptdef{sanitizesort}] This is a boolean option that +determines whether or not to \gls{sanitize} the sort value when +writing to the external glossary file. For example, suppose you +define an entry as follows: +\begin{verbatim} +\newglossaryentry{hash}{name={\#},sort={#}, + description={hash symbol}} +\end{verbatim} +The sort value (\verb|#|) must be sanitized before writing it to the +glossary file, otherwise \LaTeX\ will try to interpret it as a +parameter reference. If, on the other hand, you want the sort value +expanded, you need to switch off the sanitization. For example, +suppose you do: +\begin{verbatim} +\newcommand{\mysortvalue}{AAA} +\newglossaryentry{sample}{% + name={sample}, + sort={\mysortvalue}, + description={an example}} +\end{verbatim} +and you actually want \cs{mysortvalue} expanded, so that the entry +is sorted according to \texttt{AAA}, then use the package option +\pkgopt[false]{sanitizesort}. + +The default for \optsand23 is \pkgopt[true]{sanitizesort}, and the +default for \opt1 is \pkgopt[false]{sanitizesort}. + +\item[\pkgoptdef{savewrites}] This is a boolean option to minimise the +number of write registers used by the \styfmt{glossaries} package. +(Default is \pkgopt[false]{savewrites}.) There are only a limited +number of write registers, and if you have a large number of +glossaries or if you are using a class or other packages that +create a lot of external files, you may exceed the maximum number +of available registers. If \pkgopt{savewrites} is set, the glossary +information will be stored in token registers until the end of the +document when they will be written to the external files. + +\begin{important} +This option can significantly slow document compilation and may +cause the indexing to fail. Page numbers in the \gls{numberlist} +will be incorrect on page boundaries due to \TeX's asynchronous +output routine. As an alternative, you can use the \sty{scrwfile} +package (part of the KOMA-Script bundle) and not use this option. +\end{important} + +You can also reduce the number of write registers by using +\optsor14 or by ensuring you define all your glossary entries in the +preamble. + +\begin{important} +If you want to use \TeX's \ics{write18} mechanism to call +\gls{makeindex} or \gls{xindy} from your document and use +\pkgopt{savewrites}, you must create the external files with +\cs{glswritefiles} before you call \gls*{makeindex}/\gls*{xindy}. Also set +\cs{glswritefiles} to nothing or \cs{relax} before the end of the +document to avoid rewriting the files. For example: +\begin{verbatim} +\glswritefiles +\write18{makeindex -s \istfilename\space +-t \jobname.glg -o \jobname.gls \jobname} +\let\glswritefiles\relax +\end{verbatim} +\end{important} +In general, this package option is best avoided. + +\item[\pkgoptdef{translate}] This can take the following values: + + \begin{description} + \item[{\pkgopt[true]{translate}}] If \sty{babel} has been loaded + and the \sty{translator} package is installed, \sty{translator} + will be loaded and the translations will be provided by the + \sty{translator} package interface. You can modify the + translations by providing your own dictionary. If the + \sty{translator} package isn't installed and \sty{babel} is + loaded, the \sty{glossaries-babel} package will + be loaded and the translations will be provided using \styfmt{babel}'s + \cs{addto}\cs{caption}\meta{language} mechanism. If + \sty{polyglossia} has been loaded, \sty{glossaries-polyglossia} + will be loaded. + + \item[{\pkgopt[false]{translate}}] Don't provide translations, even + if \sty{babel} or \sty{polyglossia} has been loaded. + (Note that \sty{babel} provides the command \ics{glossaryname} + so that will still be translated if you have loaded \sty{babel}.) + + \item[{\pkgopt[babel]{translate}}] Don't load the \sty{translator} +package. Instead load \sty{glossaries-babel}. + +\begin{important} +I recommend you use \pkgopt[babel]{translate} if you have any +problems with the translations or with PDF bookmarks, but to maintain backward +compatibility, if \sty{babel} has been loaded the default is +\pkgopt[true]{translate}. +\end{important} + + \end{description} + + If \pkgopt{translate} is specified without a value, + \pkgopt[true]{translate} is assumed. If \pkgopt{translate} isn't +specified, \pkgopt[true]{translate} is assumed if \sty{babel}, +\sty{polyglossia} or \sty{translator} have been loaded. Otherwise +\pkgopt[false]{translate} is assumed. + +See \sectionref{sec:fixednames} for further details. + +\item[\pkgoptdef{notranslate}] This is equivalent to +\pkgopt[false]{translate} and may be passed via the document class +options. + +\item[\pkgoptdef{nohypertypes}] Use this option if you have multiple +glossaries and you want to suppress the entry hyperlinks for a +particular glossary or glossaries. The value of this option should +be a comma-separated list of glossary types where \ics{gls} etc +shouldn't have hyperlinks by default. Make sure you enclose the +value in braces if it contains any commas. Example: +\begin{verbatim} +\usepackage[acronym,nohypertypes={acronym,notation}] + {glossaries} +\newglossary[nlg]{notation}{not}{ntn}{Notation} +\end{verbatim} +The values must be fully expanded, so \textbf{don't} try +\texttt{nohypertypes\discretionary{}{}{}=\ics{acronymtype}}. You may also use +\begin{definition} +\ics{GlsDeclareNoHyperList}\marg{list} +\end{definition} +instead or additionally. +See \sectionref{sec:glslink} for further details. + +\item[\pkgoptdef{hyperfirst}] This is a boolean option that specifies +whether each term has a hyperlink on \firstuse. The default is +\pkgopt[true]{hyperfirst} (terms on \gls{firstuse} have a hyperlink, +unless explicitly suppressed using starred versions of commands +such as \ics{gls*} or by identifying the glossary with +\pkgopt{nohypertypes}, described above). Note that +\pkgopt{nohypertypes} overrides \pkgopt[true]{hyperfirst}. +This option only affects commands that check the \firstuseflag, such +as the \glslike\ commands (for example, \ics{gls} or +\ics{glsdisp}), but not the \glstextlike\ commands +(for example, \ics{glslink} or \ics{glstext}). + +The \pkgopt{hyperfirst} setting applies to +all glossary types (unless identified by \pkgopt{nohypertypes} or +defined with \ics{newignoredglossary}). It can be overridden on an +individual basis by explicitly setting the \gloskey[glslink]{hyper} key +when referencing an entry (or by using the plus or starred +version of the referencing command). + +It may be that you only want to apply this to just the acronyms +(where the first use explains the meaning of the acronym) but not +for ordinary glossary entries (where the first use is identical to +subsequent uses). In this case, you can use \pkgopt[false]{hyperfirst} and +apply \cs{glsunsetall} to all the regular (non-acronym) glossaries. +For example: +\begin{verbatim} + \usepackage[acronym,hyperfirst=false]{glossaries} + % acronym and glossary entry definitions + + % at the end of the preamble + \glsunsetall[main] +\end{verbatim} + +Alternatively you can redefine the hook +\begin{definition}[\DescribeMacro\glslinkcheckfirsthyperhook] +\cs{glslinkcheckfirsthyperhook} +\end{definition} +which is used by the commands that check the \firstuseflag, such +as \ics{gls}. Within the definition of this command, you can use +\ics{glslabel} to reference the entry label and \ics{glstype} to +reference the glossary type. You can also use \ics{ifglsused} +to determine if the entry has been used. You can test if an entry is +an acronym by checking if it has the \gloskey{long} key set using +\ics{ifglshaslong}. For example, to switch off the hyperlink on +first use just for acronyms: +\begin{verbatim} +\renewcommand*{\glslinkcheckfirsthyperhook}{% + \ifglsused{\glslabel}{}% + {% + \ifglshaslong{\glslabel}{\setkeys{glslink}{hyper=false}}{}% + }% +} +\end{verbatim} + +Note that this hook isn't used by the commands that don't check the +\firstuseflag, such as \ics{glstext}. (You can, instead, redefine +\ics{glslinkpostsetkeys}, which is used by both the \glslike\ and +\glstextlike\ commands.) + +\item[\pkgoptdef{indexonlyfirst}] This is a boolean option that specifies +whether to only add information to the external glossary file on +\gls{firstuse}. The default is \pkgopt[false]{indexonlyfirst}, +which will add a line to the file every time one of the +\glslike\ or \glstextlike\ commands are used. Note that \ics{glsadd} +will always add information to the external glossary +file\footnote{bug fix in v4.16 has corrected the code to ensure +this.}\ (since that's the purpose of that command). + +You can customise this by redefining +\begin{definition}[\DescribeMacro\glswriteentry] +\cs{glswriteentry}\marg{label}\marg{wr-code} +\end{definition} +where \meta{label} is the entry's label and \meta{wr-code} is the +code that writes the entry's information to the external file. +The default definition of \cs{glswriteentry} is: +\begin{verbatim} +\newcommand*{\glswriteentry}[2]{% + \ifglsindexonlyfirst + \ifglsused{#1}{}{#2}% + \else + #2% + \fi +} +\end{verbatim} +This checks the \pkgopt{indexonlyfirst} package option (using +\cs{ifglsindexonlyfirst}) and does \meta{wr-code} if this is +\pkgoptfmt{false} otherwise it only does \meta{wr-code} of the entry +hasn't been used. + +For example, suppose you only want to index the first use for +entries in the \texttt{acronym} glossary and not in the +\texttt{main} (or any other) glossary: +\begin{verbatim} +\renewcommand*{\glswriteentry}[2]{% + \ifthenelse{\equal{\glsentrytype{#1}}{acronym}} + {\ifglsused{#1}{}{#2}}% + {#2}% +} +\end{verbatim} +Here I've used \cs{ifthenelse} to ensure the arguments of +\cs{equal} are fully expanded before the comparison is made. + +\item[\pkgoptdef{savenumberlist}] This is a boolean option that +specifies whether or not to gather and store the \gls{numberlist} +for each entry. The default is \pkgopt[false]{savenumberlist}. (See +\ics{glsentrynumberlist} and \ics{glsdisplaynumberlist} in +\sectionref{sec:glsnolink}.) This is always true if you +use \opt1. + +\end{description} + +\section{Sectioning, Headings and TOC Options} +\label{sec:pkgopts-sec} + +\begin{description} +\item[\pkgoptdef{toc}] Add the glossaries to the table of contents. +Note that an extra \LaTeX\ run is required with this option. +Alternatively, you can switch this function on and off using +\begin{definition}[\DescribeMacro{\glstoctrue}] +\cs{glstoctrue} +\end{definition} +and +\begin{definition}[\DescribeMacro{\glstocfalse}] +\cs{glstocfalse} +\end{definition} + +\item[\pkgoptdef{numberline}] When used with \pkgopt{toc}, this will +add \ics{numberline}\verb|{}| in the final argument of +\ics{addcontentsline}. This will align the table of contents entry +with the numbered section titles. Note that this option has no +effect if the \pkgopt{toc} option is omitted. If \pkgopt{toc} is +used without \pkgopt{numberline}, the title will be aligned with +the section numbers rather than the section titles. + +\item[\pkgoptdef{section}] This is a \meta{key}=\meta{value} option. Its +value should be the name of a sectional unit (e.g.\ chapter). +This will make the glossaries appear in the named sectional unit, +otherwise each glossary will appear in a chapter, if chapters +exist, otherwise in a section. Unnumbered sectional units will be used +by default. Example: +\begin{verbatim} +\usepackage[section=subsection]{glossaries} +\end{verbatim} +You can omit the value if you want to use sections, i.e.\ +\begin{verbatim} +\usepackage[section]{glossaries} +\end{verbatim} +is equivalent to +\begin{verbatim} +\usepackage[section=section]{glossaries} +\end{verbatim} +You can change this value later in the document using +\begin{definition}[\DescribeMacro{\setglossarysection}] +\cs{setglossarysection}\marg{name} +\end{definition} +where \meta{name} is the sectional unit. + +The start of each glossary adds information to the page header via +\begin{definition}[\DescribeMacro{\glsglossarymark}] +\cs{glsglossarymark}\marg{glossary title} +\end{definition} +By default this uses \cs{@mkboth}\footnote{unless \cls{memoir} is +loaded, which case it uses \ics{markboth}} but you may +need to redefine it. +For example, to only change the right header: +\begin{verbatim} +\renewcommand{\glsglossarymark}[1]{\markright{#1}} +\end{verbatim} +or to prevent it from changing the headers: +\begin{verbatim} +\renewcommand{\glsglossarymark}[1]{} +\end{verbatim} +If you want \cs{glsglossarymark} to use \cs{MakeUppercase} in the header, use the +\pkgopt{ucmark} option described below. + +Occasionally you may find that another package defines +\cs{cleardoublepage} when it is not required. This may cause an +unwanted blank page to appear before each glossary. This can +be fixed by redefining \DescribeMacro\glsclearpage\cs{glsclearpage}: +\begin{verbatim} +\renewcommand*{\glsclearpage}{\clearpage} +\end{verbatim} + +\item[\pkgoptdef{ucmark}] This is a boolean option (default: +\pkgopt[false]{ucmark}, unless \cls{memoir} has been loaded, in +which case it defaults to \pkgopt[true]{ucmark}). If +set, \ics{glsglossarymark} uses +\ics{MakeTextUppercase}\footnote{Actually it uses +\ics{mfirstucMakeUppercase} which is set to \sty{textcase}'s \cs{MakeTextUppercase} +by the +\styfmt{glossaries} package. This makes it consistent with +\ics{makefirstuc}. (The \sty{textcase} package is automatically +loaded by \styfmt{glossaries}.)}. +You can test whether this option has been set or not using +\begin{definition}[\DescribeMacro\ifglsucmark] +\cs{ifglsucmark} \meta{true part}\cs{else} \meta{false part}\cs{fi} +\end{definition} +For example: +\begin{verbatim} +\renewcommand{\glsglossarymark}[1]{% + \ifglsucmark + \markright{\MakeTextUppercase{#1}}% + \else + \markright{#1}% + \fi} +\end{verbatim} +If \cls{memoir} has been loaded and \pkgopt{ucfirst} is set, then +\cls{memoir}'s \ics{memUChead} is used. + +\item[\pkgoptdef{numberedsection}] +The glossaries are placed in unnumbered sectional units by default, +but this can be changed using \pkgopt{numberedsection}. This option can take +one of the following values: +\begin{itemize} +\item \pkgoptval{false}{numberedsection}: no number, i.e.\ use starred form +of sectioning command (e.g.\ \cs{chapter*} or \cs{section*}); + +\item \pkgoptval{nolabel}{numberedsection}: +use a numbered section, i.e.\ the unstarred form of sectioning +command (e.g.\ \cs{chapter} or \cs{section}), but +the section not labelled; + +\item \pkgoptval{autolabel}{numberedsection}: numbered with automatic +labelling. Each glossary uses the unstarred form of a sectioning +command (e.g.\ \cs{chapter} or \cs{section}) and is assigned a label +(via \ics{label}). The label is formed from +\begin{definition}[\DescribeMacro{\glsautoprefix}] +\cs{glsautoprefix} \meta{type} +\end{definition} +where +\meta{type} is the label identifying that glossary. The default +value of \cs{glsautoprefix} is empty. For example, if you load \styfmt{glossaries} +using: +\begin{verbatim} +\usepackage[section,numberedsection=autolabel] + {glossaries} +\end{verbatim} +then each glossary will appear in a numbered section, and can +be referenced using something like: +\begin{verbatim} +The main glossary is in section~\ref{main} and +the list of acronyms is in section~\ref{acronym}. +\end{verbatim} +If you can't decide whether to have the acronyms in the main +glossary or a separate list of acronyms, you can use +\ics{acronymtype} which is set to \texttt{main} if the +\pkgopt{acronym} option is not used and is set to \texttt{acronym} +if the \pkgopt{acronym} option is used. For example: +\begin{verbatim} +The list of acronyms is in section~\ref{\acronymtype}. +\end{verbatim} +You can redefine the prefix if the default label clashes with +another label in your document. +For example: +\begin{verbatim} +\renewcommand*{\glsautoprefix}{glo:} +\end{verbatim} +will add \texttt{glo:} to the automatically generated label, so +you can then, for example, refer to the list of acronyms as follows: +\begin{verbatim} +The list of acronyms is in +section~\ref{glo:\acronymtype}. +\end{verbatim} +Or, if you are undecided on a prefix: +\begin{verbatim} +The list of acronyms is in +section~\ref{\glsautoprefix\acronymtype}. +\end{verbatim} + +\item \pkgoptval{nameref}{numberedsection}: this is like +\pkgoptval{autolabel}{numberedsection} but uses an unnumbered +sectioning command (e.g.\ \ics{chapter*} or \ics{section*}). It's +designed for use with the \sty{nameref} package. For example: +\begin{verbatim} +\usepackage{nameref} +\usepackage[numberedsection=nameref]{glossaries} +\end{verbatim} +Now \verb|\nameref{main}| will display the (TOC) section title +associated with the \texttt{main} glossary. As above, you can +redefine \cs{glsautoprefix} to provide a prefix for the label. +\end{itemize} + +\end{description} + +\section{Glossary Appearance Options} +\label{sec:pkgopts-printglos} + +\begin{description} +\item[\pkgoptdef{entrycounter}] This is a boolean option. (Default +is \pkgopt[false]{entrycounter}.) If set, each main (level~0) +glossary entry will be numbered when using the standard glossary +styles. This option creates the counter +\DescribeCounter{glossaryentry}\ctrfmt{glossaryentry}. + +If you use this option, you can reference the entry number +within the document using +\begin{definition}[\DescribeMacro{\glsrefentry}] +\cs{glsrefentry}\marg{label} +\end{definition} +where \meta{label} is the label associated with that glossary entry. +The labelling systems uses \meta{prefix}\meta{label}, where +\meta{label} is the entry's label and \meta{prefix} is given by +\begin{definition}[\DescribeMacro\GlsEntryCounterLabelPrefix] +\cs{GlsEntryCounterLabelPrefix} +\end{definition} +(which defaults to \texttt{glsentry-}). + +\begin{important} +If you use \cs{glsrefentry}, you must run \LaTeX\ twice after +creating the glossary files using \gls{makeglossaries}, +\gls{makeindex} or \gls{xindy} to ensure the cross-references are +up-to-date. +\end{important} + +\item[\pkgoptdef{counterwithin}] This is a \meta{key}=\meta{value} +option where \meta{value} is the name of a counter. If used, this +option will automatically set \pkgopt[true]{entrycounter} and the +\ctr{glossaryentry} counter will be reset every time \meta{value} is +incremented. + + +\begin{important} +The \ctr{glossaryentry} counter isn't automatically reset at the +start of each glossary, except when glossary section numbering is on +and the counter used by \pkgopt{counterwithin} is the same as the +counter used in the glossary's sectioning command. +\end{important} + +If you want the counter reset at the start of each glossary, you can +redefine \ics{glossarypreamble} to use +\begin{definition}[\DescribeMacro{\glsresetentrycounter}] +\cs{glsresetentrycounter} +\end{definition} +which sets \ctr{glossaryentry} to zero: +\begin{verbatim} +\renewcommand{\glossarypreamble}{% + \glsresetentrycounter +} +\end{verbatim} +or if you are using \ics{setglossarypreamble}, add it to each +glossary preamble, as required. For example: +\begin{verbatim} +\setglossarypreamble[acronym]{% + \glsresetentrycounter + The preamble text here for the list of acronyms. +} +\setglossarypreamble{% + \glsresetentrycounter + The preamble text here for the main glossary. +} +\end{verbatim} + +\item[\pkgoptdef{subentrycounter}] This is a boolean option. (Default +is \pkgopt[false]{subentrycounter}.) If set, each level~1 +glossary entry will be numbered when using the standard glossary +styles. This option creates the counter +\DescribeCounter{glossarysubentry}\ctrfmt{glossarysubentry}. +The counter is reset with each main (level~0) entry. Note that this +package option is independent of \pkgopt{entrycounter}. You can +reference the number within the document using +\ics{glsrefentry}\marg{label} where \meta{label} is the label +associated with the sub-entry. + +\item[\pkgoptdef{style}] This is a \meta{key}=\meta{value} option. +(Default is \pkgopt[list]{style}, unless \sty{classicthesis} +has been loaded, in which case the default is \pkgopt[index]{style}.) Its value should be the name of +the glossary style to use. This key may only be used for styles +defined in \sty{glossary-list}, \sty{glossary-long}, +\sty{glossary-super} or \sty{glossary-tree}. Alternatively, you can +set the style using +\begin{definition} +\cs{setglossarystyle}\marg{style name} +\end{definition} +(See \sectionref{sec:styles} for further details.) + +\item[\pkgoptdef{nolong}] This prevents the \styfmt{glossaries} package +from automatically loading \sty{glossary-long} (which means that +the \sty{longtable} package also won't be loaded). This reduces +overhead by not defining unwanted styles and commands. Note that if +you use this option, you won't be able to use any of the +glossary styles defined in the \styfmt{glossary-long} package (unless +you explicitly load \sty{glossary-long}). + +\item[\pkgoptdef{nosuper}] This prevents the \styfmt{glossaries} package +from automatically loading \sty{glossary-super} (which means that +the \sty{supertabular} package also won't be loaded). This reduces +overhead by not defining unwanted styles and commands. Note that if +you use this option, you won't be able to use any of the +glossary styles defined in the \styfmt{glossary-super} package +(unless you explicitly load \sty{glossary-super}). + +\item[\pkgoptdef{nolist}] This prevents the \styfmt{glossaries} package +from automatically loading \sty{glossary-list}. This reduces +overhead by not defining unwanted styles. Note that if +you use this option, you won't be able to use any of the +glossary styles defined in the \styfmt{glossary-list} package +(unless you explicitly load \sty{glossary-list}). +Note that since the default style is \glostyle{list} (unless +\sty{classicthesis} has been loaded), you will +also need to use the \pkgopt{style} option to set the style to +something else. + +\item[\pkgoptdef{notree}] This prevents the \styfmt{glossaries} package +from automatically loading \sty{glossary-tree}. This reduces +overhead by not defining unwanted styles. Note that if +you use this option, you won't be able to use any of the +glossary styles defined in the \styfmt{glossary-tree} package +(unless you explicitly load \sty{glossary-tree}). Note that if +\sty{classicthesis} has been loaded, the default style is +\glostyle{index}, which is provided by \sty{glossary-tree}. + +\item[\pkgoptdef{nostyles}] This prevents all the predefined styles +from being loaded. If you use this option, you need to load a +glossary style package (such as \sty{glossary-mcols}). Also if you +use this option, you can't use the \pkgopt{style} package option. +Instead you must either use \ics{setglossarystyle}\marg{style} or the +\gloskey[printglossary]{style} key in the optional argument to +\ics{printglossary}. Example: +\begin{verbatim} +\usepackage[nostyles]{glossaries} +\usepackage{glossary-mcols} +\setglossarystyle{mcoltree} +\end{verbatim} + +\item[\pkgoptdef{esclocations}] This is a boolean option. (The default +is \pkgopt[true]{esclocations}, but \ics{makenoidxglossaries} +changes it to \pkgopt[false]{esclocations}.) Both \gls{makeindex} and \gls{xindy} +are fussy about the location formats (\gls{makeindex} more so than +\gls{xindy}) so the \styfmt{glossaries} package tries to ensure that +special characters are escaped and allows for the location to be +substituted for a format that's more acceptable to the indexing +application. This requires a bit of trickery to circumvent the +problem posed by \TeX's asynchronous output routine, which can go +wrong and also adds to the complexity of the document build. + +If you're sure that your locations will always expand to an +acceptable format (or you're prepared to post-process the glossary +file before passing it to the relevant indexing application) then +use \pkgopt[false]{esclocations} to avoid the complex escaping +of location values. (See \ifpdf section~\ref*{sec:wrgloss}\fi \qt{Writing information to associated files} in the documented +code for further details.) + +\item[\pkgoptdef{nonumberlist}] This option will suppress the +associated \glspl{numberlist} in the glossaries (see also +\sectionref{sec:numberlists}). Note that if you use \optsor23 +(\gls{makeindex} or \gls{xindy}) then the locations must still be +valid. This package option merely prevents the \gls{numberlist} +from being displayed, but both \gls{makeindex} and \gls{xindy} +still require a location or cross-reference for each term that's +indexed. Remember that \gls{numberlist} includes any +cross-references, so suppressing the \gls{numberlist} will also hide +the cross-references (see below). + +\item[\pkgoptdef{seeautonumberlist}] If you suppress the +\glspl{numberlist} with \pkgopt{nonumberlist}, described above, this +will also suppress any cross-referencing information supplied by the +\gloskey{see} key in \ics{newglossaryentry} or \ics{glssee}. If you +use \pkgopt{seeautonumberlist}, the \gloskey{see} key will +automatically implement \gloskey{nonumberlist=false} for that entry. +(Note this doesn't affect \cs{glssee}.) For further details see +\sectionref{sec:crossref}. + +\item[\pkgoptdef{counter}] This is a \meta{key}=\meta{value} option. +(Default is \pkgopt[page]{counter}.) The value should be the name of +the default counter to use in the \glspl{numberlist} +(see \sectionref{sec:numberlists}). + +\item[\pkgoptdef{nopostdot}] This is a boolean option. If no value is +specified, \texttt{true} is assumed. When set to \texttt{true}, this +option suppresses the default post description dot used by some of +the predefined styles. The default setting is +\pkgopt[false]{nopostdot}. + +\item[\pkgoptdef{nogroupskip}] This is a boolean option. If no value is +specified, \texttt{true} is assumed. When set to \texttt{true}, this +option suppresses the default vertical gap between groups used by +some of the predefined styles. The default setting is +\pkgopt[false]{nogroupskip}. + +\end{description} + +\section{Sorting Options} +\label{sec:pkgopts-sort} + +\begin{description} +\item[\pkgoptdef{sort}] If you use \optsor23, this package option is +the only way of specifying how to sort the glossaries. Only \opt1 +allows you to specify sort methods for individual glossaries +via the \gloskey[printnoidxglossary]{sort} key in the optional +argument of \ics{printnoidxglossary}. If you have multiple +glossaries in your document and you are using \opt1, only use +the package options +\pkgopt[def]{sort} or \pkgopt[use]{sort} if you want to set this +sort method for \emph{all} your glossaries. + +This is a \meta{key}=\meta{value} option where +\meta{value} may be one of the following: +\begin{itemize} +\item \pkgoptval{standard}{sort} : entries are sorted according to +the value of the \gloskey{sort} key used in \ics{newglossaryentry} +(if present) or the \gloskey{name} key (if \gloskey{sort} key is +missing); + +\item \pkgoptval{def}{sort} : entries are sorted in the order in +which they were defined (the \gloskey{sort} key in +\cs{newglossaryentry} is ignored); + +\item \pkgoptval{use}{sort} : entries are sorted according to the +order in which they are used in the document (the \gloskey{sort} key +in \cs{newglossaryentry} is ignored). + +Both \pkgopt[def]{sort} and \pkgopt[use]{sort} set the sort key to a +six digit number via +\begin{definition}[\DescribeMacro\glssortnumberfmt] +\cs{glssortnumberfmt}\marg{number} +\end{definition} +(padded with leading zeros, where necessary). This can be +redefined, if required, before the entries are defined (in the +case of \pkgopt[def]{sort}) or before the entries are used +(in the case of \pkgopt[use]{sort}). + +\item \pkgoptval{none}{sort} : this setting is new to version 4.30 +and is only for documents that don't use \cs{makeglossaries} (\optsor23) +or \cs{makenoidxglossaries} (\opt1). It omits the code used to sanitize +or escape the sort value, since it's not required. This can help to +improve the document build speed, especially if there are a large +number of entries. This option +can't be used with \cs{printglossary} or \cs{printnoidxglossary} +(or the iterative versions \cs{printglossaries} or +\cs{printnoidxglossaries}). It may be used with +\sty{glossaries-extra}'s \cs{printunsrtglossary} (\opt5). +\end{itemize} +Note that the group styles (such as \glostyle{listgroup}) are +incompatible with the \pkgopt[use]{sort} and \pkgopt[def]{sort} +options. + +The default is \pkgopt[standard]{sort}. When the standard sort +option is in use, you can hook into the sort mechanism by +redefining: +\begin{definition}[\DescribeMacro{\glsprestandardsort}] +\cs{glsprestandardsort}\marg{sort cs}\marg{type}\marg{label} +\end{definition} +where \meta{sort cs} is a temporary control sequence that stores the +sort value (which was either explicitly set via the \gloskey{sort} +key or implicitly set via the \gloskey{name} key) before any escaping of the +\gls{makeindex}\slash\gls{xindy} special characters is performed. +By default \cs{glsprestandardsort} just does: +\begin{definition}[\DescribeMacro{\glsdosanitizesort}] +\cs{glsdosanitizesort} +\end{definition} +which \gls{sanitize}[s] \meta{sort cs} if the \pkgopt{sanitizesort} package +option is set (or does nothing if the package option +\pkgopt[false]{sanitizesort} is used). + +The other arguments, \meta{type} and \meta{label}, are the +glossary type and the entry label for the current entry. Note that +\meta{type} will always be a control sequence, but \meta{label} will +be in the form used in the first argument of \ics{newglossaryentry}. + +\begin{important} +Redefining \cs{glsprestandardsort} won't affect any entries that +have already been defined and will have no effect at all if you +are using \pkgopt[def]{sort} or \pkgopt[use]{sort}. +\end{important} + +\begin{example}{Mixing Alphabetical and Order of Definition Sorting}{ex:diffsorts} +Suppose I have three glossaries: \texttt{main}, +\texttt{acronym} and \texttt{notation}, and let's suppose +I want the \texttt{main} and \texttt{acronym} glossaries to be +sorted alphabetically, but the \texttt{notation} type should be +sorted in order of definition. + +For \opt1, I~just need to set the \gloskey[printnoidxglossary]{sort} key in +the optional argument of \ics{printnoidxglossary}: +\begin{verbatim} +\printnoidxglossary[sort=word] +\printnoidxglossary[type=acronym,sort=word] +\printnoidxglossary[type=notation,sort=def] +\end{verbatim} + +For \optsor23, I can set the sort to \texttt{standard} +(which is the default, but can be explicitly set via the +package option \pkgopt[standard]{sort}), and I can either define +all my \texttt{main} and \texttt{acronym} entries, then +redefine \cs{glsprestandardsort} to set \meta{sort cs} to +an incremented integer, and then define all my +\texttt{notation} entries. Alternatively, I can redefine +\cs{glsprestandardsort} to check for the glossary type and only +modify \meta{sort cs} if \meta{type} is \texttt{notation}. + +The first option can be achieved as follows: +\begin{verbatim} +\newcounter{sortcount} + +\renewcommand{\glsprestandardsort}[3]{% + \stepcounter{sortcount}% + \edef#1{\glssortnumberfmt{\arabic{sortcount}}}% +} +\end{verbatim} +The second option can be achieved as follows: +\begin{verbatim} +\newcounter{sortcount} + +\renewcommand{\glsprestandardsort}[3]{% + \ifdefstring{#2}{notation}% + {% + \stepcounter{sortcount}% + \edef#1{\glssortnumberfmt{\arabic{sortcount}}}% + }% + {% + \glsdosanitizesort + }% +} +\end{verbatim} +(\cs{ifdefstring} is defined by the \sty{etoolbox} package.) +For a complete document, see the sample file \samplefile{Sort}. +\end{example} + +\begin{example}{Customizing Standard Sort (Options 2 or 3)}{ex:customsort} +Suppose you want a glossary of people and you want the names listed +as \meta{first-name} \meta{surname} in the glossary, but you want the names +sorted by \meta{surname}, \meta{first-name}. You can do this by +defining a command called, say, +\cs{name}\marg{first-name}\marg{surname} that you can use in the +\gloskey{name} key when you define the entry, but hook into the +standard sort mechanism to temporarily redefine \cs{name} while the +sort value is being set. + +First, define two commands to set the person's name: +\begin{verbatim} +\newcommand{\sortname}[2]{#2, #1} +\newcommand{\textname}[2]{#1 #2} +\end{verbatim} +and \cs{name} needs to be initialised to \cs{textname}: +\begin{verbatim} +\let\name\textname +\end{verbatim} +Now redefine \cs{glsprestandardsort} so that it temporarily sets +\cs{name} to \cs{sortname} and expands the sort value, then sets +\cs{name} to \cs{textname} so that the person's name appears as +\meta{first-name} \meta{surname} in the text: +\begin{verbatim} +\renewcommand{\glsprestandardsort}[3]{% + \let\name\sortname + \edef#1{\expandafter\expandonce\expandafter{#1}}% + \let\name\textname + \glsdosanitizesort +} +\end{verbatim} +(The somewhat complicate use of \cs{expandafter} etc helps to +protect fragile commands, but care is still needed.) + +Now the entries can be defined: +\begin{verbatim} +\newglossaryentry{joebloggs}{name={\name{Joe}{Bloggs}}, + description={some information about Joe Bloggs}} + +\newglossaryentry{johnsmith}{name={\name{John}{Smith}}, + description={some information about John Smith}} +\end{verbatim} +For a complete document, see the sample file \samplefile{People}. +\end{example} + +\item[\pkgoptdef{order}] This may take two values: +\pkgoptval{word}{order} or \pkgoptval{letter}{order}. The default +is word ordering. + +\begin{important} +Note that the \pkgopt{order} option has no effect if you don't use +\gls{makeglossaries}. +\end{important} + +If you use \opt1, this setting will be used if you use +\gloskey[printnoidxglossary]{sort}\texttt{=standard} in +the optional argument of \ics{printnoidxglossary}: +\begin{verbatim} +\printnoidxglossary[sort=standard] +\end{verbatim} +Alternatively, you can specify the order for individual glossaries: +\begin{verbatim} +\printnoidxglossary[sort=word] +\printnoidxglossary[type=acronym,sort=letter] +\end{verbatim} + +\item[\pkgoptdef{makeindex}] (\opt2) The glossary information and +indexing style file will be written in \gls{makeindex} format. If +you use \gls{makeglossaries}, it will automatically detect that it +needs to call \gls*{makeindex}. If you don't use +\gls*{makeglossaries}, you need to remember to use \gls*{makeindex} +not \gls{xindy}. The indexing style file will been given +a~\filetype{.ist} extension. + +You may omit this package option if you are using \opt2 as this is the +default. It's available in case you need to override the effect of an earlier +occurrence of \pkgopt{xindy} in the package option list. + +\item[\pkgoptdef{xindy}] (\opt3) The glossary information and indexing style +file will be written in \gls{xindy} format. If you use +\gls{makeglossaries}, it will automatically detect that it needs to +call \gls*{xindy}. If you don't use \gls*{makeglossaries}, you need to +remember to use \gls*{xindy} not \gls{makeindex}. The indexing style +file will been given a \filetype{.xdy} extension. + +This package option may additionally have a value that +is a \meta{key}=\meta{value} comma-separated list to override the +language and codepage. For example: +\begin{verbatim} +\usepackage[xindy={language=english,codepage=utf8}] + {glossaries} +\end{verbatim} +You can also specify whether you want a number group in the +glossary. This defaults to true, but can be suppressed. For example: +\begin{verbatim} +\usepackage[xindy={glsnumbers=false}]{glossaries} +\end{verbatim} +If no value is supplied to this package option (either simply +writing \texttt{xindy} or writing \verb|xindy={}|) then the +language, codepage and number group settings are unchanged. See +\sectionref{sec:xindy} for further details on using \gls{xindy} with +the \styfmt{glossaries} package. + +\item[\pkgoptdef{xindygloss}] (\opt3) This is equivalent to +\verb|xindy={}| (that is, the \pkgopt{xindy} option without any value +supplied) and may be used as a document class option. The language +and code page can be set via \ics{GlsSetXdyLanguage} and +\ics{GlsSetXdyCodePage} (see \sectionref{sec:langenc}.) + +\item[\pkgoptdef{xindynoglsnumbers}] (\opt3) This is equivalent to +\verb|xindy={glsnumbers=false}| and may be used as a document class +option. + +\item[\pkgoptdef{automake}] This is option was introduced to +version 4.08 as a boolean option. As from version 4.42 it may now +take three values: \texttt{false} (default), \texttt{true} +or \texttt{immediate}. If no option is supplied, \texttt{immediate} +is assumed. +The option \pkgopt[true]{automake} will attempt to run \gls{makeindex} or \gls{xindy} using +\TeX's \ics{write18} mechanism at the end of the document. +The option \pkgopt[immediate]{automake} will attempt to +run \gls{makeindex} or \gls{xindy} at the start of +\ics{makeglossaries} using \cs{immediate} (before the glossary files have been opened). + +In the case of \pkgopt[true]{automake}, the associated files +are created at the end of the document ready for the next \LaTeX\ +run. Since there is a possibility of commands such as \cs{gls} +occurring on the last page of the document, it's not possible +to use \cs{immediate} to close the associated file or with +\cs{write18} since the writing of the final indexing lines may +have been delayed. In certain situations this can mean that +the \cs{write18} fails. In such cases, you will need to use +\pkgopt[immediate]{automake} instead. + +With \pkgopt[immediate]{automake}, you will get a warning on +the first \LaTeX\ run as the associated glossary files don't exist +yet. + +Since this mechanism can be a security risk, some \TeX\ +distributions disable it completely, in which case this option won't +have an effect. (If this option doesn't appear to work, search the +log file for \qt{runsystem} and see if it is followed by +\qt{enabled} or \qt{disabled}.) + +Some distributions allow \cs{write18} in a restricted mode. +This mode has a~limited number of trusted applications, which +usually includes \gls{makeindex} but may not include \gls{xindy}. So +if you have the restricted mode on, \pkgopt{automake} should work +with \gls*{makeindex} but may not work with \gls{xindy}. + +However even in unrestricted mode this option may not work with +\gls*{xindy} as \gls*{xindy} uses language names that don't always +correspond with \ics{babel}'s language names. (The +\gls{makeglossaries} script applies mappings to assist you.) +Note that you still need at least two \LaTeX\ runs to ensure the document +is up-to-date with this setting. + +Since this package option attempts to run the \gls{indexingapp} on +every \LaTeX\ run, its use should be considered a last resort for +those who can't work out how to incorporate the \gls*{indexingapp} +into their document build. The default value for this option is +\pkgopt[false]{automake}. + +\end{description} + +\section{Acronym Options} +\label{sec:pkgopts-acronym} + +\begin{description} +\item[\pkgoptdef{acronym}] This creates a new glossary with the +label \texttt{acronym}. This is equivalent to: +\begin{verbatim} +\newglossary[alg]{acronym}{acr}{acn}{\acronymname} +\end{verbatim} +It will also define +\begin{definition}[\DescribeMacro\printacronyms] +\cs{printacronyms}\oarg{options} +\end{definition} +that's equivalent to +\begin{alltt} +\ics{printglossary}[type=acronym,\meta{options}] +\end{alltt} +(unless that command is already defined before the beginning of the +document or the package option \pkgopt{compatible-3.07} is used). + +If you are using \opt1, you need to use +\begin{alltt} +\ics{printnoidxglossary}[type=acronym,\meta{options}] +\end{alltt} +to display the list of acronyms. + +If the \pkgopt{acronym} package option is used, \ics{acronymtype} +is set to \texttt{acronym} otherwise it is set to +\texttt{main}.\footnote{Actually it sets \ics{acronymtype} to +\ics{glsdefaulttype} if the \pkgopt{acronym} package option is +not used, but \ics{glsdefaulttype} usually has the value +\texttt{main} unless the \pkgopt{nomain} option has been used.} +Entries that are defined using \ics{newacronym} are placed in +the glossary whose label is given by \ics{acronymtype}, unless +another glossary is explicitly specified. + +\begin{important} +Remember to use the \pkgopt{nomain} package option if you're only +interested in using this \texttt{acronym} glossary. (That is, you +don't intend to use the \texttt{main} glossary.) +\end{important} + +\item[\pkgoptdef{acronyms}] This is equivalent to +\pkgopt[true]{acronym} and may be used in the document class option +list. + +\item[\pkgoptdef{acronymlists}] By default, only the \cs{acronymtype} +glossary is considered to be a list of acronyms. If you have other +lists of acronyms, you can specify them as a comma-separated list +in the value of \pkgopt{acronymlists}. For example, if you use the +\pkgopt{acronym} package option but you also want the \texttt{main} +glossary to also contain a list of acronyms, you can do: +\begin{verbatim} +\usepackage[acronym,acronymlists={main}]{glossaries} +\end{verbatim} +No check is performed to determine if the listed glossaries exist, +so you can add glossaries you haven't defined yet. For example: +\begin{verbatim} +\usepackage[acronym,acronymlists={main,acronym2}] + {glossaries} +\newglossary[alg2]{acronym2}{acr2}{acn2}% + {Statistical Acronyms} +\end{verbatim} +You can use +\begin{definition}[\DescribeMacro\DeclareAcronymList] +\cs{DeclareAcronymList}\marg{list} +\end{definition} +instead of or in addition to the \pkgopt{acronymlists} option. +This will add the glossaries given in \meta{list} to the list of glossaries +that are identified as lists of acronyms. To replace the list of acronym lists +with a new list use: +\begin{definition}[\DescribeMacro\SetAcronymLists] +\cs{SetAcronymLists}\marg{list} +\end{definition} + +You can determine if a glossary has been identified as being a list +of acronyms using: +\begin{definition}[\DescribeMacro\glsIfListOfAcronyms] +\cs{glsIfListOfAcronyms}\marg{label}\marg{true part}\marg{false part} +\end{definition} + +\item[\pkgoptdef{shortcuts}] This option provides shortcut commands +for acronyms. See \sectionref{sec:acronyms} for further details. +Alternatively you can use: +\begin{definition}[\DescribeMacro\DefineAcronymSynonyms] +\cs{DefineAcronymSynonyms} +\end{definition} +\end{description} + +\subsection{Deprecated Acronym Style Options} +\label{sec:pkgopts-old-acronym} + +The package options listed in this section are now deprecated but +are kept for backward-compatibility. Use \ics{setacronymstyle} +instead. See \sectionref{sec:acronyms} for further details. + +\begin{description} +\item[\pkgoptdef{description}] This option changes the definition of +\ics{newacronym} to allow a description. +This option may be replaced by +\begin{verbatim} +\setacronymstyle{long-short-desc} +\end{verbatim} +or (with \pkgopt{smallcaps}) +\begin{verbatim} +\setacronymstyle{long-sc-short-desc} +\end{verbatim} +or (with \pkgopt{smaller}) +\begin{verbatim} +\setacronymstyle{long-sm-short-desc} +\end{verbatim} +or (with \pkgopt{footnote}) +\begin{verbatim} +\setacronymstyle{footnote-desc} +\end{verbatim} +or (with \pkgopt{footnote} and \pkgopt{smallcaps}) +\begin{verbatim} +\setacronymstyle{footnote-sc-desc} +\end{verbatim} +or (with \pkgopt{footnote} and \pkgopt{smaller}) +\begin{verbatim} +\setacronymstyle{footnote-sm-desc} +\end{verbatim} +or (with \pkgopt{dua}) +\begin{verbatim} +\setacronymstyle{dua-desc} +\end{verbatim} + +\item[\pkgoptdef{smallcaps}] This option changes the definition of +\ics{newacronym} and the way that acronyms are displayed. +This option may be replaced by: +\begin{verbatim} +\setacronymstyle{long-sc-short} +\end{verbatim} +or (with \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{long-sc-short-desc} +\end{verbatim} +or (with \pkgopt{description} and \pkgopt{footnote}) +\begin{verbatim} +\setacronymstyle{footnote-sc-desc} +\end{verbatim} + +\item[\pkgoptdef{smaller}] This option changes the definition of +\ics{newacronym} and the way that acronyms are displayed. +\begin{important} +If you use this option, you will need to include the \sty{relsize} +package or otherwise define \ics{textsmaller} or redefine +\ics{acronymfont}. +\end{important} +This option may be replaced by: +\begin{verbatim} +\setacronymstyle{long-sm-short} +\end{verbatim} +or (with \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{long-sm-short-desc} +\end{verbatim} +or (with \pkgopt{description} and \pkgopt{footnote}) +\begin{verbatim} +\setacronymstyle{footnote-sm-desc} +\end{verbatim} + +\item[\pkgoptdef{footnote}] This option changes the definition of +\ics{newacronym} and the way that acronyms are displayed. +This option may be replaced by: +\begin{verbatim} +\setacronymstyle{footnote} +\end{verbatim} +or (with \pkgopt{smallcaps}) +\begin{verbatim} +\setacronymstyle{footnote-sc} +\end{verbatim} +or (with \pkgopt{smaller}) +\begin{verbatim} +\setacronymstyle{footnote-sm} +\end{verbatim} +or (with \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{footnote-desc} +\end{verbatim} +or (with \pkgopt{smallcaps} and \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{footnote-sc-desc} +\end{verbatim} +or (with \pkgopt{smaller} and \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{footnote-sm-desc} +\end{verbatim} + + +\item[\pkgoptdef{dua}] This option changes the definition of +\ics{newacronym} so that acronyms are always expanded. +This option may be replaced by: +\begin{verbatim} +\setacronymstyle{dua} +\end{verbatim} +or (with \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{dua-desc} +\end{verbatim} + +\end{description} + +\section{Other Options} +\label{sec:pkgopts-other} + +Other available options that don't fit any of the above categories +are: +\begin{description} +\item[\pkgoptdef{symbols}] This option defines a new glossary type with +the label \texttt{symbols} via +\begin{verbatim} +\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname} +\end{verbatim} +It also defines +\begin{definition}[\DescribeMacro\printsymbols] +\cs{printsymbols}\oarg{options} +\end{definition} +which is a synonym for +\begin{alltt} +\ics{printglossary}[type=symbols,\meta{options}] +\end{alltt} + +If you use \opt1, you need to use: +\begin{alltt} +\ics{printnoidxglossary}[type=symbols,\meta{options}] +\end{alltt} +to display the list of symbols. + +\begin{important} +Remember to use the \pkgopt{nomain} package option if you're only +interested in using this \texttt{symbols} glossary and don't intend +to use the \texttt{main} glossary. +\end{important} + +The \styfmt{glossaries-extra} package has a slightly modified +version of this option which additionally provides \ics{glsxtrnewsymbol} +as a convenient shortcut method for defining symbols. See the +\styfmt{glossaries-extra} manual for further details. + +\item[\pkgoptdef{numbers}] This option defines a new glossary type with +the label \texttt{numbers} via +\begin{verbatim} +\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname} +\end{verbatim} +It also defines +\begin{definition}[\DescribeMacro\printnumbers] +\cs{printnumbers}\oarg{options} +\end{definition} +which is a synonym for +\begin{alltt} +\ics{printglossary}[type=numbers,\meta{options}] +\end{alltt} + +If you use \opt1, you need to use: +\begin{alltt} +\ics{printnoidxglossary}[type=numbers,\meta{options}] +\end{alltt} +to display the list of numbers. + +\begin{important} +Remember to use the \pkgopt{nomain} package option if you're only +interested in using this \texttt{numbers} glossary and don't intend +to use the \texttt{main} glossary. +\end{important} + +The \styfmt{glossaries-extra} package has a slightly modified +version of this option which additionally provides \ics{glsxtrnewnumber} +as a convenient shortcut method for defining numbers. See the +\styfmt{glossaries-extra} manual for further details. + +\item[\pkgoptdef{index}] This option defines a new glossary type with +the label \texttt{index} via +\begin{verbatim} +\newglossary[ilg]{index}{ind}{idx}{\indexname}% +\end{verbatim} +It also defines +\begin{definition}[\DescribeMacro\newterm] +\cs{newterm}\oarg{options}\marg{term} +\end{definition} +which is a synonym for +\begin{alltt} +\ics{newglossaryentry}\marg{term}[type=index,name=\marg{term},% +description=\ics{nopostdesc},\meta{options}] +\end{alltt} +and +\begin{definition}[\DescribeMacro\printindex] +\cs{printindex}\oarg{options} +\end{definition} +which is a synonym for +\begin{alltt} +\ics{printglossary}[type=index,\meta{options}] +\end{alltt} + +If you use \opt1, you need to use: +\begin{alltt} +\ics{printnoidxglossary}[type=index,\meta{options}] +\end{alltt} +to display this glossary. + +\begin{important} +Remember to use the \pkgopt{nomain} package option if you're only +interested in using this \texttt{index} glossary and don't intend to +use the \texttt{main} glossary. Note that you +can't mix this option with \ics{index}. Either use +\styfmt{glossaries} for the indexing or use a~custom indexing +package, such as \sty{makeidx}, \sty{index} or \sty{imakeidx}. +(You can, of course, load one of those packages and +load \styfmt{glossaries} without the \pkgopt{index} package option.) +\end{important} + +Since the index isn't designed for terms with descriptions, you +might also want to disable the hyperlinks for this glossary using +the package option \pkgopt[index]{nohypertypes} or the command +\begin{display} +\ics{GlsDeclareNoHyperList}\verb|{index}| +\end{display} + +The example file \samplefile{-index} illustrates the use of the +\pkgopt{index} package option. + +\item[\pkgoptdef{noglossaryindex}] This option switches off \pkgopt{index} +if \pkgopt{index} has been passed implicitly (for example, +through global document options). This option can't be used +in \cs{setupglossaries}. + +\item[\pkgoptdef{compatible-2.07}] Compatibility mode for old documents +created using version 2.07 or below. + +\item[\pkgoptdef{compatible-3.07}] Compatibility mode for old documents +created using version 3.07 or below. + +\item[\pkgoptdef{kernelglossredefs}] As a legacy from the precursor +\sty{glossary} package, the standard glossary commands provided +by the \LaTeX\ kernel (\cs{makeglossary} and \cs{glossary}) are +redefined in terms of the \styfmt{glossaries} package's commands. +However, they were never documented in this user manual, and the +conversion guide (\htmldoc{Upgrading from the glossary package to the +glossaries package}{glossary2glossaries}) explicitly discourages +their use. + +The use of those kernel commands (instead of the appropriate +commands documented in this user guide) are deprecated, and you will +now get a warning if you try using them. + +In the event that you require the original form of these kernel +commands, for example, if you need to use the \styfmt{glossaries} +package with another class or package that also performs +glossary-style indexing, then you can restore these commands to +their previous definition (that is, their definitions prior to +loading the \styfmt{glossaries} package) with the package option +\pkgopt[false]{kernelglossredefs}. You may also need to use the +\pkgopt{nomain} option in the event of file extension conflicts. +(In which case, you must provide a new default glossary for use with +the \sty{glossaries} package.) + +This option may take one of three values: \pkgoptfmt{true} +(redefine with warnings, default), \pkgoptfmt{false} (restore +previous definitions) or \pkgoptfmt{nowarn} (redefine without +warnings, not recommended). + +Note that the only glossary-related commands provided by the \LaTeX\ +kernel are \cs{makeglossary} and \cs{glossary}. Other packages +or classes may provide additional glossary-related commands or +environments that conflict with \styfmt{glossaries} (such as +\cs{printglossary} and \env{theglossary}). These non-kernel commands +aren't affected by this package option, and you will have to find +some way to resolve the conflict if you require both glossary +mechanisms. (The \sty{glossaries} package will override the existing +definitions of \cs{printglossary} and \env{theglossary}.) + +In general, if possible, it's best to stick with just one package that +provides a glossary mechanism. (The \styfmt{glossaries} package does +check for the \sty{doc} package and patches \cs{PrintChanges}.) + +\end{description} + +\section{Setting Options After the Package is Loaded} +\label{sec:setupglossaries} + +Some of the options described above may also be set after the +\styfmt{glossaries} package has been loaded using +\begin{definition}[\DescribeMacro{\setupglossaries}] +\cs{setupglossaries}\marg{key-val list} +\end{definition} +The following package options \textbf{can't} be used in +\cs{setupglossaries}: \pkgopt{xindy}, \pkgopt{xindygloss}, +\pkgopt{xindynoglsnumbers}, \pkgopt{makeindex}, +\pkgopt{nolong}, \pkgopt{nosuper}, \pkgopt{nolist}, +\pkgopt{notree}, \pkgopt{nostyles}, \pkgopt{nomain}, +\pkgopt{compatible-2.07}, \pkgopt{translate}, \pkgopt{notranslate}, +\pkgopt{acronym}. These options have to be set while the package is +loading, except for the \pkgopt{xindy} sub-options which can be set +using commands like \ics{GlsSetXdyLanguage} (see +\sectionref{sec:xindy} for further details). + +\begin{important} +If you need to use this command, use it as soon as +possible after loading \styfmt{glossaries} otherwise you might +end up using it too late for the change to take effect. For example, +if you try changing the acronym styles (such as \pkgopt{smallcaps}) +after you have started defining your acronyms, you are likely to get +unexpected results. If you try changing the sort option after you have +started to define entries, you may get unexpected results. +\end{important} + +\chapter{Setting Up} +\label{sec:setup} + +In the preamble you need to indicate whether you want to use \opt1, +\opt2 or \opt3. It's not possible to mix these options within +a~document, although some combinations are possible with +\gls*{glossaries-extra}. (For \optsand45 see the \gls{bib2gls} and +\gls{glossaries-extra} manuals.) + +\section[Option 1]{\ifpdf\opt1\else Option 1\fi} +\label{sec:setupopt1} + +The command +\begin{definition}[\DescribeMacro{\makenoidxglossaries}] +\cs{makenoidxglossaries} +\end{definition} +must be placed in the preamble. This sets up the internal commands +required to make \opt1 work. +\textbf{If you omit \cs{makenoidxglossaries} none of +the glossaries will be displayed.} + +\section[Options 2 and 3]{\ifpdf\optsand23\else Options 2 and 3\fi} +\label{sec:setupopt23} + +The command +\begin{definition}[\DescribeMacro{\makeglossaries}] +\cs{makeglossaries} +\end{definition} +must be placed in the preamble in order to create the customised +\gls{makeindex} (\filetype{.ist}) or \gls{xindy} (\filetype{.xdy}) +style file (for \optsor23, respectively) and to ensure that glossary +entries are written to the appropriate output files. +\textbf{If you omit \cs{makeglossaries} none of +the glossary files will be created.} + +\begin{important} +Note that some of the commands provided by the \styfmt{glossaries} +package must not be used after \cs{makeglossaries} as they are +required when creating the customised style file. If you attempt +to use those commands after \cs{makeglossaries} you will generate +an error. + +Similarly, there are some commands that must not be used before +\cs{makeglossaries}. +\end{important} + +You can suppress the creation of the customised \gls{xindy} +or \gls{makeindex} style file using +\begin{definition}[\DescribeMacro{\noist}] +\cs{noist} +\end{definition} +That this command must not be used after \cs{makeglossaries}. +\begin{important} +Note that if you have a custom \filetype{.xdy} file created when using +\styfmt{glossaries} version 2.07 or below, you will need to use the +\pkgopt{compatible-2.07} package option with it. +\end{important} + +The default name for the customised style file is given by +\ics{jobname}\filetype{.ist} (\opt2) or +\ics{jobname}\filetype{.xdy} (\opt3). This name may be +changed using: +\begin{definition}[\DescribeMacro{\setStyleFile}] +\cs{setStyleFile}\marg{name} +\end{definition} +where \meta{name} is the name of the style file without the +extension. Note that this command must not be used after +\cs{makeglossaries}. + +Each glossary entry is assigned a \gls{numberlist} that lists all +the locations in the document where that entry was used. By default, +the location refers to the page number but this may be overridden +using the \pkgopt{counter} package option. The default form of +the location number assumes a full stop compositor (e.g.\ 1.2), +but if your location numbers use a different compositor (e.g. 1-2) +you need to set this using +\begin{definition}[\DescribeMacro{\glsSetCompositor}] +\cs{glsSetCompositor}\marg{symbol} +\end{definition} +For example: +\begin{verbatim} +\glsSetCompositor{-} +\end{verbatim} +This command must not be used after \cs{makeglossaries}. + +If you use \opt3, you can have a different compositor for page +numbers starting with an upper case alphabetical character using: +\begin{definition}[\DescribeMacro{\glsSetAlphaCompositor}] +\cs{glsSetAlphaCompositor}\marg{symbol} +\end{definition} +This command has no effect if you use \opt2. For example, if you want +\glspl{numberlist} containing a mixture of A-1 and 2.3 style +formats, then do: +\begin{verbatim} +\glsSetCompositor{.}\glsSetAlphaCompositor{-} +\end{verbatim} +See \sectionref{sec:numberlists} for further information about +\glspl{numberlist}. + +\chapter{Defining Glossary Entries} +\label{sec:newglosentry} + +All glossary entries must be defined before they are used, so it is +better to define them in the preamble to ensure this. In fact, some +commands such as \cs{longnewglossaryentry} +may only be used in the preamble. See \sectionref{sec:docdefs} for +a discussion of the problems with defining entries within the +document instead of in the preamble. (The \gls{glossaries-extra} +package has an option that provides a restricted form of document +definitions that avoids some of the issues discussed in +\sectionref{sec:docdefs}.) +\begin{important} +\opt1 enforces the preamble-only restriction on +\ics{newglossaryentry}. \opt4 requires that definitions are provided +in \texttt{.bib} format. \opt5 requires either preamble-only +definitions or the use of the \sty{glossaries-extra} package option +\optfmt{docdef=restricted}. +\end{important} + +Only those entries that are indexed in the document +(using any of the commands described in +\sectionref{sec:glslink}, \sectionref{sec:glsadd} or +\sectionref{sec:crossref}) will appear in the glossary. See +\sectionref{sec:printglossary} to find out how to display the +glossary. + + +New glossary entries are defined using the command: +\begin{definition}[\DescribeMacro{\newglossaryentry}] +\cs{newglossaryentry}\marg{label}\marg{key=value list} +\end{definition} +This is a short command, so values in \meta{key-val list} can't +contain any paragraph breaks. Take care to enclose values containing +any commas (\texttt{,}) or equal signs (\texttt{=}) with braces to hide them +from the key=value list parser. Be careful to ensure that no +spurious spaces are included at the start and end of the braces. + +If you have a long description that +needs to span multiple paragraphs, use +\begin{definition}[\DescribeMacro{\longnewglossaryentry}] +\cs{longnewglossaryentry}\marg{label}\marg{key=value +list}\marg{long description} +\end{definition} +instead. Note that this command may only be used in the preamble. +Be careful of unwanted spaces. \cs{longnewglossaryentry} +will remove trailing spaces in the description (via \cs{unskip}) +but won't remove leading spaces (otherwise it would interfere with +commands like \cs{Glsentrydesc}). This command also appends +\cs{nopostdesc} to the end of the description, which suppresses the +post-description hook. The \sty{glossaries-extra} package provides +a starred version of \cs{longnewglossaryentry} that doesn't append +either \cs{unskip} or \cs{nopostdesc}. + +There are also commands that will only define the entry if it +hasn't already been defined: +\begin{definition}[\DescribeMacro\provideglossaryentry] +\cs{provideglossaryentry}\marg{label}\marg{key=value list} +\end{definition} +and +\begin{definition}[\DescribeMacro\longprovideglossaryentry] +\cs{longprovideglossaryentry}\marg{label}\marg{key=value +list}\marg{long description} +\end{definition} +(These are both preamble-only commands.) + +For all the above commands, the first argument, \meta{label}, must be +a~unique label with which to identify this entry. \textbf{This can't contain +any non-expandable commands or active characters.} The reason for +this restriction is that the label is used to construct internal commands +that store the associated information (similarly to commands +like \cs{label}) and therefore must be able to expand to a valid +control sequence name. + +\begin{important} +Note that although an \gls{exlatinchar} or other \gls{nonlatinchar}, +such as \'e or \ss, looks like a plain character in your +\texttt{.tex} file, it's actually a~macro (an active character) and +therefore can't be used in the label. (This applies to \LaTeX\ +rather than \XeLaTeX.) Also be careful of +\sty{babel}'s options that change certain punctuation characters +(such as \texttt{:} or \texttt{-}) to active characters. +\end{important} + +The second argument, \meta{key=value list}, is +a \meta{key}=\meta{value} list that supplies the relevant +information about this entry. There are two required fields: +\gloskey{description} and either \gloskey{name} or \gloskey{parent}. +The description is set in the third argument of +\cs{longnewglossaryentry} and \cs{longprovideglossaryentry}. With +the other commands it's set via the \gloskey{description} key. +As is typical with \meta{key}=\meta{value} lists, values that contain +a comma or equal sign must be enclosed in braces. Available fields +are listed below. Additional fields are provided by the +supplementary packages \sty{glossaries-prefix} +(\sectionref{sec:prefix}) and \sty{glossaries-accsupp} +(\sectionref{sec:accsupp}) and also by \gls{glossaries-extra}. +You can also define your own custom keys (see +\sectionref{sec:addkey}). + +\begin{description} +\item[{\gloskey{name}}] The name of the entry (as it will appear in +the glossary). If this key is omitted and the \gloskey{parent} +key is supplied, this value will be the same as the parent's name. + +\begin{important} +If the \gloskey{name} key contains any commands, you must also +use the \gloskey{sort} key (described below) if you intend sorting the entries +alphabetically, otherwise the entries can't be sorted correctly. +\end{important} + +\item[{\gloskey{description}}] A brief description of this term (to +appear in the glossary). Within this value, you can use +\begin{definition}[\DescribeMacro{\nopostdesc}] +\cs{nopostdesc} +\end{definition} +to suppress the +description terminator for this entry. For example, if this +entry is a parent entry that doesn't require a description, you +can do \verb|description={\nopostdesc}|. If you want a paragraph +break in the description use +\begin{definition}[\DescribeMacro{\glspar}] +\cs{glspar} +\end{definition} +or, better, use \cs{longnewglossaryentry}. +However, note that not all glossary styles support multi-line +descriptions. If you are using one of the tabular-like glossary +styles that permit multi-line descriptions, use \ics{newline} +not \verb"\\" if you want to force a line break. + +\item[{\gloskey{parent}}] The label of the parent entry. Note that +the parent entry must be defined before its sub-entries. +See \sectionref{sec:subentries} for further details. + +\item[{\gloskey{descriptionplural}}] The plural form of the +description, if required. If omitted, the value +is set to the same as the \gloskey{description} key. + +\item[{\gloskey{text}}] How this entry will appear in the document text +when using \ics{gls} (or one of its upper case variants). If this +field is omitted, the value of the \gloskey{name} key is used. + +\item[{\gloskey{first}}] How the entry will appear in the document text +on \firstuse\ with \ics{gls} (or one of its upper case +variants). If this field is omitted, the value of the \gloskey{text} +key is used. Note that if you use \ics{glspl}, \ics{Glspl}, +\ics{GLSpl}, \ics{glsdisp} before using \ics{gls}, the +\gloskey{firstplural} value won't be used with \ics{gls}. + +\item[{\gloskey{plural}}] How the entry will appear in the document text +when using \ics{glspl} (or one of its upper case variants). If this +field is omitted, the value is obtained by appending +\ics{glspluralsuffix} to the value of the \gloskey{text} field. The +default value of \ics{glspluralsuffix} is the letter \qt{s}. + +\item[{\gloskey{firstplural}}] How the entry will appear in the +document text on \firstuse\ with \ics{glspl} (or one of its +upper case variants). If this field is omitted, the value is obtained +from the \gloskey{plural} key, if the \gloskey{first} key is omitted, +or by appending \ics{glspluralsuffix} to the value of the +\gloskey{first} field, if the \gloskey{first} field is present. Note +that if you use \ics{gls}, \ics{Gls}, \ics{GLS}, \cs{glsdisp} before +using \ics{glspl}, the \gloskey{firstplural} value won't be used +with \ics{glspl}. + +\textbf{Note:} prior to version 1.13, the default value of +\gloskey{firstplural} was always taken by appending \qt{s} to the +\gloskey{first} key, which meant that you had to specify both +\gloskey{plural} and \gloskey{firstplural}, even if you hadn't +used the \gloskey{first} key. + +\item[{\gloskey{symbol}}] This field is provided to allow the user +to specify an associated symbol. If omitted, the value is set to +\cs{relax}. Note that not all glossary styles display the symbol. + +\item[{\gloskey{symbolplural}}] This is the plural form of the +symbol (as passed to \ics{glsdisplay} and \ics{glsdisplayfirst} +by \ics{glspl}, \ics{Glspl} and \ics{GLSpl}). If omitted, the value +is set to the same as the \gloskey{symbol} key. + +\item[{\gloskey{sort}}] This value indicates how this entry should +be sorted. If omitted, the value is given +by the \gloskey{name} field unless one of the package options +\pkgopt[def]{sort} and \pkgopt[use]{sort} have been used. In +general, it's best to use the \gloskey{sort} key if the +\gloskey{name} contains commands (e.g.\ \verb|\ensuremath{\alpha}|). +You can also override the \gloskey{sort} key by redefining +\ics{glsprestandardsort} (see \sectionref{sec:pkgopts-sort}). + +\opt1 by default strips the \glslink{latexexlatinchar}{standard +\LaTeX\ accents} (that is, accents generated by core \LaTeX\ commands) from the +\gloskey{name} key when it sets the \gloskey{sort} key. So with +\opt1: +\begin{verbatim} +\newglossaryentry{elite}{% + name={{\'e}lite}, + description={select group of people} +} +\end{verbatim} +This is equivalent to: +\begin{verbatim} +\newglossaryentry{elite}{% + name={{\'e}lite}, + description={select group of people}, + sort={elite} +} +\end{verbatim} +Unless you use the package option \pkgopt[true]{sanitizesort}, in +which case it's equivalent to: +\begin{verbatim} +\newglossaryentry{elite}{% + name={{\'e}lite}, + description={select group of people}, + sort={\'elite} +} +\end{verbatim} +This will place the entry before the \qt{A} letter group since the +sort value starts with a symbol. + +Similarly if you use the \sty{inputenc} package: +\begin{alltt} +\verb|\newglossaryentry{elite}{%| + name=\verb|{{|\'e\verb|}|lite\verb|}|, + description=\verb|{select group of people}| +\verb|}| +\end{alltt} +This is equivalent to +\begin{alltt} +\verb|\newglossaryentry{elite}{%| + name=\verb|{{|\'e\verb|}|lite\verb|}|, + description=\verb|{select group of people}|, + sort=elite +\verb|}| +\end{alltt} +Unless you use the package option \pkgopt[true]{sanitizesort}, in +which case it's equivalent to: +\begin{alltt} +\verb|\newglossaryentry{elite}{%| + name=\verb|{{|\'e\verb|}|lite\verb|}|, + description=\verb|{select group of people}|, + sort=\'elite +\verb|}| +\end{alltt} +Again, this will place the entry before the \qt{A} group. + +With \optsand23, the default value of \gloskey{sort} will either be +set to the \gloskey{name} key (if \pkgopt[true]{sanitizesort}) or it +will set it to the expansion of the \gloskey{name} key (if +\pkgopt[false]{sanitizesort}). + +\begin{important} +Take care with \gls{xindy} (\opt3): if you have entries with the same +\gloskey{sort} value they will be treated as the +same entry. If you use \gls{xindy} and aren't using the \texttt{def} +or \texttt{use} sort methods, \textbf{always} use the \gloskey{sort} +key for entries where the name just consists of a control sequence +(for example \texttt{name=\{\cs{alpha}\}}). + +Take care if you use \opt1 and the \gloskey{name} contains fragile +commands. You will either need to explicitly set the \gloskey{sort} +key or use the \pkgopt[true]{sanitizesort} package option (unless +you use the \texttt{def} or \texttt{use} sort methods). +\end{important} + +\item[{\gloskey{type}}] This specifies the label of the glossary in +which this entry belongs. If omitted, the default glossary is +assumed unless \ics{newacronym} is used (see +\sectionref{sec:acronyms}). + +\item[{\gloskey{user1}, \ldots, \gloskey{user6}% +\igloskey{user2}\igloskey{user3}\igloskey{user4}\igloskey{user5}}] +Six keys provided for any additional information the user may want +to specify. (For example, an associated dimension or an alternative +plural or some other grammatical construct.) Alternatively, you can +add new keys using \ics{glsaddkey} or \ics{glsaddstoragekey} (see \sectionref{sec:addkey}). + +\item[{\gloskey{nonumberlist}}] A boolean key. If the value is +missing or is \texttt{true}, this will suppress the \gls{numberlist} just for +this entry. Conversely, if you have used the package option +\pkgopt{nonumberlist}, you can activate the \gls*{numberlist} just +for this entry with \gloskey{nonumberlist=false}. +(See \sectionref{sec:numberlists}.) + +\item[{\gloskey{see}}] Cross-reference another entry. Using the +\gloskey{see} key will \emph{automatically add this entry to the +glossary}, but will not automatically add the cross-referenced entry. +The referenced entry should be supplied as the value to this key. +If you want to override the \qt{see} tag, you can supply the new +tag in square brackets before the label. For example +\verb|see=[see also]{anotherlabel}|. \textbf{Note that if you have +suppressed the \gls{numberlist}, the cross-referencing information +won't appear in the glossary, as it forms part of the +\gls*{numberlist}.} You can override this for individual +glossary entries using \gloskey{nonumberlist=false} (see above). +Alternatively, you can use the \pkgopt{seeautonumberlist} package +option. For further details, see \sectionref{sec:crossref}. + +This key essentially provides a convenient shortcut that performs +\begin{alltt} +\cs{glssee}\oarg{tag}\marg{label}\marg{xr-label list} +\end{alltt} +after the entry has been defined. + +\begin{important} +For \optsand23, \ics{makeglossaries} must be used before any occurrence of +\ics{newglossaryentry} that contains the \gloskey{see} key. This key +should not be used with entries defined in the \env{document} environment. +\end{important} +Since it's useful to suppress the indexing while working on a draft +document, consider using the \pkgopt{seenoindex} package option to +warn or ignore the \gloskey{see} key while \cs{makeglossaries} is +commented out. + +If you use the \gloskey{see} key, you may want to consider using the +\gls{glossaries-extra} package which additionally +provides a \texttt{seealso} and \texttt{alias} key. If you want to +avoid the automatic indexing triggered by the \gloskey{see} key, +consider using \opt4. + +\end{description} + +The following keys are reserved for \ics{newacronym} (see +\sectionref{sec:acronyms}): \gloskey{long}, \gloskey{longplural}, +\gloskey{short} and \gloskey{shortplural}. + +\begin{important} +Avoid using any of the \glslike\ or \glstextlike\ commands within +the \gloskey{text}, \gloskey{first}, \gloskey{short} or +\gloskey{long} keys (or their plural equivalent) or any +other key that you plan to access through those commands. +(For example, the \gloskey{symbol} key if you intend to use +\cs{glssymbol}.) Otherwise you end up with nested links, which +can cause complications and they won't work with the case-changing +commands. You can use them within the value of keys +that won't be accessed through those commands. For example, +the \gloskey{description} key if you don't use \cs{glsdesc}. +Additionally, they'll confuse the entry formatting commands, such as +\cs{glslabel}. +\end{important} + +Note that if the name starts with +\gls{nonlatinchar}, you must group the character, otherwise it will +cause a problem for commands like \ics{Gls} and \ics{Glspl}. +For example: +\begin{verbatim} +\newglossaryentry{elite}{name={{\'e}lite}, +description={select group or class}} +\end{verbatim} +Note that the same applies if you are using the \sty{inputenc} +package: +\begin{alltt} +\verb|\newglossaryentry{elite}{name={{|\'e\verb|}lite},| +description=\verb|{select group or class}}| +\end{alltt} +(This doesn't apply for \XeLaTeX\ documents using the \sty{fontspec} +package. For further details, see the \qt{UTF-8} section in the +\sty{mfirstuc} user manual.) + +Note that in both of the above examples, you will also need to +supply the \gloskey{sort} key if you are using \opt2 +whereas \gls{xindy} (\opt3) is usually able to sort +\glspl{nonlatinchar} +correctly. \opt1 discards accents from +\glspl{latexexlatinchar} unless you use the \pkgopt[true]{sanitizesort}. + + +\section{Plurals} +\label{sec:plurals} + +You may have noticed from above that you can specify the plural form +when you define a term. If you omit this, the plural will be +obtained by appending +\begin{definition}[\DescribeMacro{\glspluralsuffix}] +\cs{glspluralsuffix} +\end{definition} +to the singular form. This command defaults to the letter \qt{s}. +For example: +\begin{verbatim} +\newglossaryentry{cow}{name=cow,description={a fully grown +female of any bovine animal}} +\end{verbatim} +defines a new entry whose singular form is \qt{cow} and plural form +is \qt{cows}. However, if you are writing in archaic English, you +may want to use \qt{kine} as the plural form, in which case you +would have to do: +\begin{verbatim} +\newglossaryentry{cow}{name=cow,plural=kine, +description={a fully grown female of any bovine animal}} +\end{verbatim} + +If you are writing in a language that supports +multiple plurals (for a given term) then use the \gloskey{plural} key +for one of them and one of the user keys to specify the +other plural form. For example: +\begin{verbatim} +\newglossaryentry{cow}{% + name=cow,% + description={a fully grown female of any bovine animal + (plural cows, archaic plural kine)},% + user1={kine}} +\end{verbatim} +You can then use \verb|\glspl{cow}| to produce \qt{cows} and +\verb|\glsuseri{cow}| to produce \qt{kine}. You can, of course, +define an easy to remember synonym. For example: +\begin{verbatim} +\let\glsaltpl\glsuseri +\end{verbatim} +Then you don't have to remember which key you used to store the +second plural. Alternatively, you can define your own keys using +\ics{glsaddkey}, described in \sectionref{sec:addkey}. + +If you are using a language that usually forms plurals +by appending a different letter, or sequence of letters, you can +redefine \cs{glspluralsuffix} as required. However, this must be +done \emph{before} the entries are defined. For languages that don't +form plurals by simply appending a suffix, all the plural forms must be +specified using the \gloskey{plural} key (and the \gloskey{firstplural} +key where necessary). + +\section{Other Grammatical Constructs} +\label{sec:grammar} + +You can use the six user keys to provide alternatives, such as +participles. For example: +\begin{verbatim} +\let\glsing\glsuseri +\let\glsd\glsuserii + +\newcommand*{\ingkey}{user1} +\newcommand*{\edkey}{user2} + +\newcommand*{\newword}[3][]{% + \newglossaryentry{#2}{% + name={#2},% + description={#3},% + \edkey={#2ed},% + \ingkey={#2ing},#1% + }% +} +\end{verbatim} +With the above definitions, I can now define terms like this: +\begin{verbatim} +\newword{play}{to take part in activities for enjoyment} +\newword[\edkey={ran},\ingkey={running}]{run}{to move fast using +the legs} +\end{verbatim} +and use them in the text: +\begin{verbatim} +Peter is \glsing{play} in the park today. + +Jane \glsd{play} in the park yesterday. + +Peter and Jane \glsd{run} in the park last week. +\end{verbatim} + +Alternatively, you can define your own keys using +\ics{glsaddkey}, described below in \sectionref{sec:addkey}. + +\section{Additional Keys} +\label{sec:addkey} + +You can now also define your own custom keys using the +commands described in this section. There are two types of keys: +those for use within the document and those to store information +used behind the scenes by other commands. + +For example, if you want to add a key that indicates the associated +unit for a~term, you might want to reference this unit in your +document. In this case use \cs{glsaddkey} described in +\sectionref{sec:glsaddkey}. If, on the other hand, you want to add a +key to indicate to a glossary style or acronym style that this entry +should be formatted differently to other entries, then you can use +\cs{glsaddstoragekey} described in \sectionref{sec:glsaddstoragekey}. + +In both cases, a new command \meta{no link cs} will be defined that +can be used to access the value of this key (analogous to commands +such as \cs{glsentrytext}). This can be used in an expandable +context (provided any fragile commands stored in the key have been +protected). The new keys must be added using \cs{glsaddkey} or +\cs{glsaddstoragekey} before glossary entries are defined. + +\subsection{Document Keys} +\label{sec:glsaddkey} + +A custom key that can be used in the document is defined using: +\begin{definition}[\DescribeMacro\glsaddkey] +\cs{glsaddkey}\marg{key}% +\marg{default value}% +\marg{no link cs}% +\marg{no link ucfirst cs}% +\marg{link cs}% +\marg{link ucfirst cs}% +\marg{link allcaps cs} +\end{definition} +where: +\begin{description} +\item[\meta{key}] is the new key to use in \ics{newglossaryentry} +(or similar commands such as \ics{longnewglossaryentry}); +\item[\meta{default value}] is the default value to use if this key +isn't used in an entry definition (this may reference the current +entry label via \cs{glslabel}, but you will have to switch on +expansion via the starred version of \cs{glsaddkey} and protect +fragile commands); +\item[\meta{no link cs}] is the control sequence to use analogous +to commands like \ics{glsentrytext}; +\item[\meta{no link ucfirst cs}] is the control sequence to use analogous +to commands like \ics{Glsentrytext}; +\item[\meta{link cs}] is the control sequence to use analogous +to commands like \ics{glstext}; +\item[\meta{link ucfirst cs}] is the control sequence to use analogous +to commands like \ics{Glstext}; +\item[\meta{link allcaps cs}] is the control sequence to use analogous +to commands like \ics{GLStext}. +\end{description} +The starred version of \cs{glsaddkey} switches on expansion for this +key. The unstarred version doesn't override the current expansion +setting. + +\begin{example}{Defining Custom Keys}{ex:addkey} +Suppose I want to define two new keys, \texttt{ed} and \texttt{ing}, +that default to the entry text followed by \qt{ed} and \qt{ing}, +respectively. The default value will need expanding in both cases, so +I need to use the starred form: +\begin{verbatim} + % Define "ed" key: + \glsaddkey* + {ed}% key + {\glsentrytext{\glslabel}ed}% default value + {\glsentryed}% command analogous to \glsentrytext + {\Glsentryed}% command analogous to \Glsentrytext + {\glsed}% command analogous to \glstext + {\Glsed}% command analogous to \Glstext + {\GLSed}% command analogous to \GLStext + + % Define "ing" key: + \glsaddkey* + {ing}% key + {\glsentrytext{\glslabel}ing}% default value + {\glsentrying}% command analogous to \glsentrytext + {\Glsentrying}% command analogous to \Glsentrytext + {\glsing}% command analogous to \glstext + {\Glsing}% command analogous to \Glstext + {\GLSing}% command analogous to \GLStext +\end{verbatim} +Now I can define some entries: +\begin{verbatim} + % No need to override defaults for this entry: + + \newglossaryentry{jump}{name={jump},description={}} + + % Need to override defaults on these entries: + + \newglossaryentry{run}{name={run},% + ed={ran},% + ing={running},% + description={}} + + \newglossaryentry{waddle}{name={waddle},% + ed={waddled},% + ing={waddling},% + description={}} +\end{verbatim} + +These entries can later be used in the document: +\begin{verbatim} +The dog \glsed{jump} over the duck. + +The duck was \glsing{waddle} round the dog. + +The dog \glsed{run} away from the duck. +\end{verbatim} +For a complete document, see the sample file \samplefile{-newkeys}. +\end{example} + +\subsection{Storage Keys} +\label{sec:glsaddstoragekey} + +A custom key that can be used for simply storing information is +defined using: +\begin{definition}[\DescribeMacro\glsaddstoragekey] +\cs{glsaddstoragekey}\marg{key}\marg{default value}\marg{no link cs} +\end{definition} +where the arguments are as the first three arguments of +\cs{glsaddkey}, described above in \sectionref{sec:glsaddkey}. + +This is essentially the same as \cs{glsaddkey} except that it +doesn't define the additional commands. You can access or update +the value of your new field using the commands described in +\sectionref{sec:fetchset}. + +\begin{example}{Defining Custom Storage Key (Acronyms and Initialisms)}{ex:addstoragekey} +Suppose I want to define acronyms and other forms of abbreviations, +such as initialisms, but I want them all in the same glossary and I +want the acronyms on first use to be displayed with the short form followed by +the long form in parentheses, but the opposite way round for other +forms of abbreviations. (The \gls{glossaries-extra} package +provides a simpler way of achieving this.) + +Here I can define a new key that determines whether the term is +actually an acronym rather than some other form of abbreviation. I'm +going to call this key \texttt{abbrtype} (since \texttt{type} +already exists): +\begin{verbatim} +\glsaddstoragekey + {abbrtype}% key/field name + {word}% default value if not explicitly set + {\abbrtype}% custom command to access the value if required +\end{verbatim} + +Now I can define a style that looks up the value of this new key to +determine how to display the full form: +\begin{verbatim} +\newacronymstyle + {mystyle}% style name + {% Use the generic display + \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}% + } + {% Put the long form in the description + \renewcommand*{\GenericAcronymFields}{% + description={\the\glslongtok}}% + % For the full format, test the value of the "abbrtype" key. + % If it's set to "word" put the short form first with + % the long form in brackets. + \renewcommand*{\genacrfullformat}[2]{% + \ifglsfieldeq{##1}{abbrtype}{word} + {% is a proper acronym + \protect\firstacronymfont{\glsentryshort{##1}}##2\space + (\glsentrylong{##1})% + } + {% is another form of abbreviation + \glsentrylong{##1}##2\space + (\protect\firstacronymfont{\glsentryshort{##1}})% + }% + }% + % first letter upper case version: + \renewcommand*{\Genacrfullformat}[2]{% + \ifglsfieldeq{##1}{abbrtype}{word} + {% is a proper acronym + \protect\firstacronymfont{\Glsentryshort{##1}}##2\space + (\glsentrylong{##1})% + } + {% is another form of abbreviation + \Glsentrylong{##1}##2\space + (\protect\firstacronymfont{\glsentryshort{##1}})% + }% + }% + % plural + \renewcommand*{\genplacrfullformat}[2]{% + \ifglsfieldeq{##1}{abbrtype}{word} + {% is a proper acronym + \protect\firstacronymfont{\glsentryshortpl{##1}}##2\space + (\glsentrylong{##1})% + } + {% is another form of abbreviation + \glsentrylongpl{##1}##2\space + (\protect\firstacronymfont{\glsentryshortpl{##1}})% + }% + }% + % plural and first letter upper case + \renewcommand*{\Genplacrfullformat}[2]{% + \ifglsfieldeq{##1}{abbrtype}{word} + {% is a proper acronym + \protect\firstacronymfont{\Glsentryshortpl{##1}}##2\space + (\glsentrylong{##1})% + } + {% is another form of abbreviation + \Glsentrylongpl{##1}##2\space + (\protect\firstacronymfont{\glsentryshortpl{##1}})% + }% + }% + % Just use the short form as the name part in the glossary: + \renewcommand*{\acronymentry}[1]{% + \acronymfont{\glsentryshort{##1}}}% + % Sort by the short form: + \renewcommand*{\acronymsort}[2]{##1}% + % Just use the surrounding font for the short form: + \renewcommand*{\acronymfont}[1]{##1}% + % Same for first use: + \renewcommand*{\firstacronymfont}[1]{\acronymfont{##1}}% + % Default plural suffix if the plural isn't explicitly set + \renewcommand*{\acrpluralsuffix}{\glspluralsuffix}% + } +\end{verbatim} +Remember that the new style needs to be set before defining any +terms: +\begin{verbatim} +\setacronymstyle{mystyle} +\end{verbatim} + +Since it's a bit confusing to use \ics{newacronym} for something +that's not technically an acronym, let's define a new command for +initialisms: +\begin{verbatim} +\newcommand*{\newinitialism}[4][]{% + \newacronym[abbrtype=initialism,#1]{#2}{#3}{#4}% +} +\end{verbatim} +Now the entries can all be defined: +\begin{verbatim} +\newacronym{radar}{radar}{radio detecting and ranging} +\newacronym{laser}{laser}{light amplification by stimulated +emission of radiation} +\newacronym{scuba}{scuba}{self-contained underwater breathing +apparatus} +\newinitialism{dsp}{DSP}{digital signal processing} +\newinitialism{atm}{ATM}{automated teller machine} +\end{verbatim} +On \gls{firstuse}, \verb|\gls{radar}| will produce \qt{radar (radio +detecting and ranging)} but \verb|\gls{dsp}| will produce \qt{DSP +(digital signal processing)}. + +For a complete document, see the sample file +\samplefile{-storage-abbr}. +\end{example} + +In the above example, if \cs{newglossaryentry} is explicitly used +(instead of through \cs{newacronym}) the \texttt{abbrtype} key will +be set to its default value of \qt{word} but the \cs{ifglshaslong} +test in the custom acronym style will be false (since the +\gloskey{long} key hasn't been set) so the display style will switch +to that given by \cs{glsgenentryfmt} and they'll be no test +performed on the \texttt{abbrtype} field. + +\begin{example}{Defining Custom Storage Key (Acronyms and +Non-Acronyms with Descriptions)}{ex:addstoragekey2} +The previous example can be modified if the \gloskey{description} +also needs to be provided. Here I've changed \qt{word} to +\qt{acronym}: +\begin{verbatim} +\glsaddstoragekey + {abbrtype}% key/field name + {acronym}% default value if not explicitly set + {\abbrtype}% custom command to access the value if required +\end{verbatim} +This may seem a little odd for non-abbreviated entries defined using +\cs{newglossaryentry} directly, but \ics{ifglshaslong} can be used +to determine whether or not to reference the value of this new +\texttt{abbrtype} field. + +The new acronym style has a~minor modification that forces the user +to specify a description. In the previous example, the line: +\begin{verbatim} + \renewcommand*{\GenericAcronymFields}{% + description={\the\glslongtok}}% +\end{verbatim} +needs to be changed to: +\begin{verbatim} + \renewcommand*{\GenericAcronymFields}{}% +\end{verbatim} +Additionally, to accommodate the change in the default value of the +\texttt{abbrtype} key, all instances of +\begin{verbatim} + \ifglsfieldeq{##1}{abbrtype}{word} +\end{verbatim} +need to be changed to: +\begin{verbatim} + \ifglsfieldeq{##1}{abbrtype}{acronym} +\end{verbatim} + +Once this new style has been set, the new acronyms can be defined +using the optional argument to set the description: +\begin{verbatim} +\newacronym[description={system for detecting the position and +speed of aircraft, ships, etc}]{radar}{radar}{radio detecting +and ranging} +\end{verbatim} + +No change is required for the definition of \cs{newinitialism} but +again the optional argument is required to set the description: +\begin{verbatim} +\newinitialism[description={mathematical manipulation of an +information signal}]{dsp}{DSP}{digital signal processing} +\end{verbatim} + +We can also accommodate contractions in a similar manner to the +initialisms: +\begin{verbatim} +\newcommand*{\newcontraction}[4][]{% + \newacronym[abbrtype=contraction,#1]{#2}{#3}{#4}% +} +\end{verbatim} +The contractions can similarly been defined using this new command: +\begin{verbatim} +\newcontraction[description={front part of a ship below the +deck}]{focsle}{fo'c's'le}{forecastle} +\end{verbatim} + +Since the custom acronym style just checks if \texttt{abbrtype} is +\texttt{acronym}, the contractions will be treated the same as the +initialisms, but the style could be modified by a further test of +the \texttt{abbrtype} value if required. + +To test regular non-abbreviated entries, I've also defined a simple +word: +\begin{verbatim} +\newglossaryentry{apple}{name={apple},description={a fruit}} +\end{verbatim} + +Now for a new glossary style that provides information about the +abbreviation (in addition to the description): +\begin{verbatim} +\newglossarystyle + {mystyle}% style name + {% base it on the "list" style + \setglossarystyle{list}% + \renewcommand*{\glossentry}[2]{% + \item[\glsentryitem{##1}% + \glstarget{##1}{\glossentryname{##1}}] + \ifglshaslong{##1}% + { (\abbrtype{##1}: \glsentrylong{##1})\space}{}% + \glossentrydesc{##1}\glspostdescription\space ##2}% + } +\end{verbatim} +This uses \ics{ifglshaslong} to determine whether or not the term is +an abbreviation. If it has an abbreviation, the full form is +supplied in parentheses and \cs{abbrtype} (defined by +\cs{glsaddstoragekey} earlier) is used to indicate the type of +abbreviation. + +With this style set, the \texttt{apple} entry is simply displayed in +the glossary as +\begin{description} +\item[apple] a fruit. +\end{description} +but the abbreviations are displayed in the form +\begin{description} +\item[laser] (acronym: light amplification by +stimulated emission of radiation) device that creates a narrow beam +of intense light. +\end{description} +(for acronyms) or +\begin{description} +\item[DSP] (initialism: digital signal processing) mathematical +manipulation of an information signal. +\end{description} +(for initalisms) or +\begin{description} +\item[fo'c's'le] (contraction: forecastle) front part of a ship +below the deck. +\end{description} +(for contractions). + +For a complete document, see \samplefile{-storage-abbr-desc}. +\end{example} + +\section{Expansion} +\label{sec:expansion} + +When you define new glossary entries expansion is performed by +default, except for the \gloskey{name}, \gloskey{description}, +\gloskey{descriptionplural}, \gloskey{symbol}, \gloskey{symbolplural} +and \gloskey{sort} keys (these keys all have expansion suppressed via +\cs{glssetnoexpandfield}). + +You can switch expansion on or off for individual keys using +\begin{definition}[\DescribeMacro\glssetexpandfield] +\cs{glssetexpandfield}\marg{field} +\end{definition} +or +\begin{definition}[\DescribeMacro\glssetnoexpandfield] +\cs{glssetnoexpandfield}\marg{field} +\end{definition} +respectively, where \meta{field} is the field tag corresponding to +the key. In most cases, this is the same as the name of the key +except for those listed in \tableref{tab:fieldmap}. + +\begin{table}[htbp] +\caption{Key to Field Mappings} +\label{tab:fieldmap} +\centering +\begin{tabular}{ll} +\bfseries Key & \bfseries Field\\ +\gloskey{sort} & \ttfamily sortvalue\\ +\gloskey{firstplural} & \ttfamily firstpl\\ +\gloskey{description} & \ttfamily desc\\ +\gloskey{descriptionplural} & \ttfamily descplural\\ +\gloskey{user1} & \ttfamily useri\\ +\gloskey{user2} & \ttfamily userii\\ +\gloskey{user3} & \ttfamily useriii\\ +\gloskey{user4} & \ttfamily useriv\\ +\gloskey{user5} & \ttfamily userv\\ +\gloskey{user6} & \ttfamily uservi\\ +\gloskey{longplural} & \ttfamily longpl\\ +\gloskey{shortplural} & \ttfamily shortpl +\end{tabular} +\end{table} + +Any keys that haven't had the expansion explicitly set using +\cs{glssetexpandfield} or \cs{glssetnoexpandfield} are governed by +\begin{definition}[\DescribeMacro\glsexpandfields] +\cs{glsexpandfields} +\end{definition} +and +\begin{definition}[\DescribeMacro\glsnoexpandfields] +\cs{glsnoexpandfields} +\end{definition} + +If your entries contain any fragile commands, I recommend you switch +off expansion via \cs{glsnoexpandfields}. (This should be used +before you define the entries.) + +\section{Sub-Entries} +\label{sec:subentries} + +As from version 1.17, it is possible to specify sub-entries. These +may be used to order the glossary into categories, in which case the +sub-entry will have a different name to its parent entry, or it may +be used to distinguish different definitions for the same word, in +which case the sub-entries will have the same name as the parent +entry. Note that not all glossary styles support hierarchical +entries and may display all the entries in a flat format. Of the +styles that support sub-entries, some display the sub-entry's name +whilst others don't. Therefore you need to ensure that you use a +suitable style. (See \sectionref{sec:styles} for a list of predefined +styles.) As from version 3.0, level~1 sub-entries are automatically +numbered in the predefined styles if you use the +\pkgopt{subentrycounter} package option (see +\sectionref{sec:pkgopts-printglos} for further details). + +Note that the parent entry will automatically be added to the +glossary if any of its child entries are used in the document. +If the parent entry is not referenced in the document, it will not +have a \gls{numberlist}. Note also that \gls{makeindex} has a +restriction on the maximum sub-entry depth. + +\subsection{Hierarchical Categories} +\label{sec:hierarchical} + +To arrange a glossary with hierarchical categories, you need to +first define the category and then define the sub-entries using the +relevant category entry as the value of the \gloskey{parent} key. + +\begin{example}{Hierarchical Categories---Greek and Roman +Mathematical Symbols}{ex:hierarchical} + +Suppose I want a glossary of mathematical symbols that +are divided into Greek letters and Roman letters. Then I can define +the categories as follows: +\begin{verbatim} +\newglossaryentry{greekletter}{name={Greek letters}, +description={\nopostdesc}} + +\newglossaryentry{romanletter}{name={Roman letters}, +description={\nopostdesc}} +\end{verbatim} + +Note that in this example, the category entries don't need a +description so I have set the descriptions to \ics{nopostdesc}. +This gives a blank description and suppresses the +description terminator. + +I can now define my sub-entries as follows: +\begin{verbatim} +\newglossaryentry{pi}{name={\ensuremath{\pi}},sort={pi}, +description={ratio of the circumference of a circle to +the diameter}, +parent=greekletter} + +\newglossaryentry{C}{name={\ensuremath{C}},sort={C}, +description={Euler's constant}, +parent=romanletter} +\end{verbatim} +For a complete document, see the sample file \samplefile{tree}. +\end{example} + +\subsection{Homographs} +\label{sec:homographs} + +Sub-entries that have the same name as the parent entry, don't need +to have the \gloskey{name} key. For example, the word \qt{glossary} +can mean a list of technical words or a collection of glosses. In +both cases the plural is \qt{glossaries}. So first define the parent +entry: +\begin{verbatim} +\newglossaryentry{glossary}{name=glossary, +description={\nopostdesc}, +plural={glossaries}} +\end{verbatim} +Again, the parent entry has no description, so the description +terminator needs to be suppressed using \ics{nopostdesc}. + +Now define the two different meanings of the word: +\begin{verbatim} +\newglossaryentry{glossarylist}{ +description={list of technical words}, +sort={1}, +parent={glossary}} + +\newglossaryentry{glossarycol}{ +description={collection of glosses}, +sort={2}, +parent={glossary}} +\end{verbatim} +Note that if I reference the parent entry, the location will be +added to the parent's \gls{numberlist}, whereas if I reference any +of the child entries, the location will be added to the child +entry's number list. Note also that since the sub-entries have the +same name, the \gloskey{sort} key is required unless you are using +the \pkgopt[use]{sort} or \pkgopt[def]{sort} package options (see +\sectionref{sec:pkgopts-sort}). You +can use the \pkgopt{subentrycounter} package option to automatically +number the first-level child entries. See +\sectionref{sec:pkgopts-printglos} for further details. + +In the above example, the plural form for both of the child entries +is the same as the parent entry, so the \gloskey{plural} key was +not required for the child entries. However, if the sub-entries +have different plurals, they will need to be specified. For example: +\begin{verbatim} +\newglossaryentry{bravo}{name={bravo}, +description={\nopostdesc}} + +\newglossaryentry{bravocry}{description={cry of approval +(pl.\ bravos)}, +sort={1}, +plural={bravos}, +parent=bravo} + +\newglossaryentry{bravoruffian}{description={hired +ruffian or killer (pl.\ bravoes)}, +sort={2}, +plural={bravoes}, +parent=bravo} +\end{verbatim} + + +\section{Loading Entries From a File} +\label{sec:loadglsentries} + +You can store all your glossary entry definitions in another +file and use: +\begin{definition}[\DescribeMacro{\loadglsentries}] +\cs{loadglsentries}\oarg{type}\marg{filename} +\end{definition} +where \meta{filename} is the name of the file containing all the +\ics{newglossaryentry} or \ics{longnewglossaryentry} commands. +The optional argument +\meta{type} is the name of the glossary to which those entries +should belong, for those entries where the \gloskey{type} key has +been omitted (or, more specifically, for those entries whose +type has been specified by \ics{glsdefaulttype}, which is what +\ics{newglossaryentry} uses by default). + +This is a~preamble-only command. You may also use \ics{input} to load +the file but don't use \ics{include}. If you find that your file is +becoming unmanageably large, you may want to consider switching to +\gls{bib2gls} and use an application such as JabRef to manage the +entry definitions. + +\begin{important} +If you want to use \ics{AtBeginDocument} to \cs{input} all your entries +automatically at the start of the document, add the +\cs{AtBeginDocument} command \emph{before} you load the +\sty{glossaries} package (and \sty{babel}, if you are also loading +that) to avoid the creation of the +\filetype{.glsdefs} file and any associated problems that are caused +by defining commands in the \env{document} environment. +(See \sectionref{sec:docdefs}.) +\end{important} + +\begin{example}{Loading Entries from Another File}{ex:loadgls} +Suppose I have a file called \texttt{myentries.tex} which contains: +\begin{verbatim} +\newglossaryentry{perl}{type=main, +name={Perl}, +description={A scripting language}} + +\newglossaryentry{tex}{name={\TeX}, +description={A typesetting language},sort={TeX}} + +\newglossaryentry{html}{type=\glsdefaulttype, +name={html}, +description={A mark up language}} +\end{verbatim} +and suppose in my document preamble I use the command: +\begin{verbatim} +\loadglsentries[languages]{myentries} +\end{verbatim} +then this will add the entries \texttt{tex} and \texttt{html} +to the glossary whose type is given by \texttt{languages}, but +the entry \texttt{perl} will be added to the main glossary, since +it explicitly sets the type to \texttt{main}. +\end{example} + +\textbf{Note:} if you use \ics{newacronym} (see +\sectionref{sec:acronyms}) the type is set as +\verb|type=\acronymtype| unless you explicitly override it. For +example, if my file \texttt{myacronyms.tex} contains: +\begin{verbatim} +\newacronym{aca}{aca}{a contrived acronym} +\end{verbatim} +then (supposing I have defined a new glossary type called +\texttt{altacronym}) +\begin{verbatim} +\loadglsentries[altacronym]{myacronyms} +\end{verbatim} +will add \texttt{aca} to the glossary type \texttt{acronym}, if the +package option \pkgopt{acronym} has been specified, or will add +\texttt{aca} to the glossary type \texttt{altacronym}, if the +package option \pkgopt{acronym} is not specified.\footnote{This is +because \ics{acronymtype} is set to \ics{glsdefaulttype} if the +\pkgopt{acronym} package option is not used.} + +If you have used the \pkgopt{acronym} package option, +there are two possible solutions to this problem: +\begin{enumerate} +\item Change \texttt{myacronyms.tex} so that entries are defined in +the form: +\begin{verbatim} +\newacronym[type=\glsdefaulttype]{aca}{aca}{a +contrived acronym} +\end{verbatim} +and do: +\begin{verbatim} +\loadglsentries[altacronym]{myacronyms} +\end{verbatim} + +\item Temporarily change \cs{acronymtype} to the target glossary: +\begin{verbatim} +\let\orgacronymtype\acronymtype +\renewcommand{\acronymtype}{altacronym} +\loadglsentries{myacronyms} +\let\acronymtype\orgacronymtype +\end{verbatim} +\end{enumerate} + +Note that only those entries that have been used +in the text will appear in the relevant glossaries. +Note also that \cs{loadglsentries} may only be used in the +preamble. + +Remember that you can use \ics{provideglossaryentry} rather than +\ics{newglossaryentry}. Suppose you want to maintain a large database +of acronyms or terms that you're likely to use in your documents, +but you may want to use a modified version of some of those entries. +(Suppose, for example, one document may require a more detailed +description.) Then if you define the entries using +\cs{provideglossaryentry} in your database file, you can override +the definition by simply using \cs{newglossaryentry} before loading +the file. For example, suppose your file (called, say, +\texttt{terms.tex}) contains: +\begin{verbatim} +\provideglossaryentry{mallard}{name=mallard, + description={a type of duck}} +\end{verbatim} +but suppose your document requires a more detailed description, you +can do: +\begin{verbatim} +\usepackage{glossaries} +\makeglossaries + +\newglossaryentry{mallard}{name=mallard, + description={a dabbling duck where the male has a green head}} + +\loadglsentries{terms} +\end{verbatim} +Now the \texttt{mallard} definition in the \texttt{terms.tex} file +will be ignored. + +\section{Moving Entries to Another Glossary} +\label{sec:moveentry} + +As from version~3.02, you can move an entry from one glossary to +another using: +\begin{definition}[\DescribeMacro{\glsmoveentry}] +\cs{glsmoveentry}\marg{label}\marg{target glossary label} +\end{definition} +where \meta{label} is the unique label identifying the required +entry and \meta{target glossary label} is the unique label +identifying the glossary in which to put the entry. + +Note that no check is performed to determine the existence of +the target glossary. If you want to move an entry to a glossary +that's skipped by \ics{printglossaries}, then define an ignored +glossary with \ics{newignoredglossary}. (See +\sectionref{sec:newglossary}.) + +\begin{important} +Unpredictable results may occur if you move an entry to a different +glossary from its parent or children. +\end{important} + +\section{Drawbacks With Defining Entries in the Document Environment} +\label{sec:docdefs} + +Originally, \ics{newglossaryentry} (and \ics{newacronym}) could only be +used in the preamble. I reluctantly removed this restriction in version 1.13, +but there are issues with defining commands in the \env{document} +environment instead of the preamble, which is why the restriction is +maintained for newer commands. This restriction is also reimposed +for \cs{newglossaryentry} by the new \opt1. (The +\gls{glossaries-extra} package automatically reimposes this restriction for +\optsand23 but provides a package option to allow document +definitions.) + +\subsection{Technical Issues} +\label{sec:techissues} + +\begin{enumerate} + \item If you define an entry mid-way through your document, but +subsequently shuffle sections around, you could end up using an +entry before it has been defined. + + \item Entry information is required when displaying the glossary. +If this occurs at the start of the document, but the entries aren't +defined until later, then the entry details are +being looked up before the entry has been defined. + + \item If you use a package, such as \sty{babel}, that makes +certain characters active at the start of the \env{document} +environment, there will be a~problem if those characters have +a~special significance when defining glossary entries. +These characters include the double-quote \verb|"| character, the +exclamation mark \texttt{!} character, the question mark \verb|?| +character, and the pipe \verb"|" character. They +must not be active when defining a~glossary entry where they occur +in the \gloskey{sort} key (and they should be avoided in the label +if they may be active at any point in the document). Additionally, +the comma \texttt{,} character and the equals \texttt{=} character +should not be active when using commands that have +\meta{key}=\meta{value} arguments. + +\end{enumerate} + +To overcome the first two problems, as from version 4.0 the +\styfmt{glossaries} package modifies the definition of +\cs{newglossaryentry} at the beginning of the \env{document} +environment so that the definitions are written to an external file +(\cs{jobname}\filetype{.glsdefs}) which is then read in at the start +of the document on the next run. The entry will then only be defined +in the \env{document} environment if it doesn't already exist. This +means that the entry can now be looked up in the glossary, even if +the glossary occurs at the beginning of the document. + +There are drawbacks to this mechanism: if you modify an entry +definition, you need a second run to see the effect of your +modification; this method requires an extra \cs{newwrite}, which may +exceed \TeX's maximum allocation; unexpected expansion issues could +occur; the \gloskey{see} key isn't stored, which means it can't be +added to the \filetype{.glsdefs} file when it's created at the end of the +document (and therefore won't be present on subsequent runs). + +The \gls{glossaries-extra} package provides a setting (but only for +\optsand23) that allows \cs{newglossaryentry} to occur in the +document environment but doesn't create the \filetype{.glsdefs} +file. This circumvents some problems but it means that you can't +display any of the glossaries before all the entries have been +defined (so it's all right if all the glossaries are at the end of +the document but not if any occur in the front matter). + +\subsection{Good Practice Issues} +\label{sec:goodpractice} + +The above section covers technical issues that can cause your document to have +compilation errors or produce incorrect output. This section +focuses on good writing practice. The main reason cited by users +wanting to define entries within the \env{document} environment rather +than in the preamble is that they want to write the definition as +they type in their document text. This suggests a \qt{stream of +consciousness} style of writing that may be acceptable in certain +literary genres but is inappropriate for factual documents. + +When you write technical documents, regardless of whether it's a PhD +thesis or an article for a~journal or proceedings, you must plan what you write +in advance. If you plan in advance, you should have a fairly good +idea of the type of terminology that your document will contain, +so while you are planning, create a new file with all your entry +definitions. If, while you're writing your document, you remember +another term you need, then you can switch over to your definition file and +add it. Most text editors have the ability to have more than one +file open at a time. The other advantage to this approach is that if +you forget the label, you can look it up in the definition file +rather than searching through your document text to find the +definition. + +\chapter{Number lists} +\label{sec:numberlists} + +Each entry in the glossary has an associated \gls{numberlist}. +By default, these numbers refer to the pages on which that entry has +been indexed (using any of the commands described in +\sectionref{sec:glslink} and \sectionref{sec:glsadd}). The number +list can be suppressed using the \pkgopt{nonumberlist} package +option, or an alternative counter can be set as the default using +the \pkgopt{counter} package option. The number list is also +referred to as the location list\index{location list|see{number list}}. + +\Glspl{numberlist} are more common with indexes rather than +glossaries (although you can use the \styfmt{glossaries} package for +indexes as well). However, the \styfmt{glossaries} package makes use +of \gls{makeindex} or \gls{xindy} to hierarchically sort and collate the +entries since they are readily available with most modern \TeX\ +distributions. Since these are both designed as \glspl{indexingapp} +they both require that terms either have a valid location or a +cross-reference. Even if you use \pkgopt{nonumberlist}, the +locations must still be provided and acceptable to the +\gls{indexingapp} or they will cause an error during the indexing +stage, which will interrupt the document build. However, if you're +not interested in the locations, each entry only needs to be indexed +once, so consider using \pkgopt{indexonlyfirst}, which can improve the +document build time by only indexing the \gls{firstuse} of each term. + +The \ics{glsaddall} command (see \sectionref{sec:glsadd}), which is used to +automatically index all entries, iterates over all defined entries +and does \cs{glsadd}\marg{label} for each entry (where \meta{label} +is that entry's label). This means that \cs{glsaddall} automatically +adds the same location to every entry's \gls{numberlist}, which +looks weird if the \gls*{numberlist} hasn't been suppressed. + +With \opt4, the indexing is performed by \gls{bib2gls}, which was +specifically designed for the \gls{glossaries-extra} package. So it +will allow any location format, and its \texttt{selection=all} +option will select all entries without adding an unwanted location to the +\gls{numberlist}. If \gls{bib2gls} can deduce a numerical value for +a location, it will attempt to form a range over consecutive +locations, otherwise it won't try to form a range and the +location will just form an individual item in the list. +\opt1 also allows any location but it doesn't form ranges. + +\section{Encap Values} +\label{sec:encap} + +Each location in the \gls{numberlist} is encapsulated with a +command formed from the \termdef{encap} value. By +default this is the \ics{glsnumberformat} command, which corresponds +to the encap \texttt{glsnumberformat}, but this may be +overridden using the \gloskey[glslink]{format} key in the optional +argument to commands like \cs{gls}. (See \sectionref{sec:glslink}.) +For example, you may want the location to appear in bold to indicate +the principle use of a term or symbol. If the encap starts with an +open parenthesis~\verb|(| this signifies the start of a range and if +the encap starts with close parenthesis~\verb|)| this signifies the +end of a range. These must always occur in matching pairs. + +The \styfmt{glossaries} package provides the command \ics{glsignore} +which ignores its argument. This is the format used by +\cs{glsaddallunused} to suppress the location, which works fine as +long as no other locations are added to the \gls{numberlist}. For +example, if you use \verb|\gls{sample}| on page~2 then reset the +\gls{firstuseflag} and then use \cs{glsaddallunused} on page~10, the +\gls{numberlist} for \texttt{sample} will be \verb|2, \glsignore{10}| +which will result in \qt{2,~} which has a spurious comma. + +This isn't a problem with \gls{bib2gls} because you'd use +\texttt{selection=all} instead of \cs{glsaddallunused}, but even if +you explicitly had, for example, +\cs{gls}\texttt{[format=glsignore]}\marg{label} +for some reason, \gls{bib2gls} will recognise \texttt{glsignore} as +a special encap indicating an ignored location, so it will select +the entry but not add that location to the \gls{numberlist}. It's a +problem for all the other options (except \opt5, which doesn't +perform any indexing). + +Complications can arise if you use different encap values for the +same location. For example, suppose on page~10 you have both the +default \texttt{glsnumberformat} and \texttt{textbf} encaps. While it may +seem apparent that \texttt{textbf} should override \texttt{glsnumberformat} +in this situation, the \gls{indexingapp} may not know it. +This is therefore something you need to be careful about if you use the +\gloskey[glslink]{format} key or if you use a command that +implicitly sets it. + +In the case of \gls{xindy}, it only accepts one encap (according to +the order of precedence given in the \gls{xindy} module) and discards the +others for identical locations (for the same entry). This can cause +a problem if a discarded location forms the start or end of a range. + +In the case of \gls{makeindex}, it accepts different encaps for the +same location, but warns about it. This leads to a \gls{numberlist} +with the same location repeated in different formats. If you use +the \gls{makeglossaries} Perl script with \opt2 it will detect +\gls{makeindex}'s warning and attempt to fix the problem, ensuring +that the \texttt{glsnumberformat} encap always has the least precedence +unless it includes a range identifier. Other conflicting encaps will +have the last one override earlier ones for the same location with +range identifiers taking priority. + +No discard occurs with \opt1 so again you get the same location +repeated in different formats. With \opt4, \gls{bib2gls} will discard +according to order of precedence, giving priority to start and end +range encaps. (See the \gls{bib2gls} manual for further details.) + +\section{Locations} +\label{sec:locationsyntax} + +Neither \opt1 nor \opt4 care about the location syntax as long as +it's valid \LaTeX\ code (and doesn't contain fragile commands). In +both cases, the indexing is performed by writing a line to the +\texttt{.aux} file. The write operation is deferred to avoid the +problems associated with \TeX's asynchronous output routine. +(See, for example, +\href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}{Finding +if you're on an odd or an even page} for more details on this issue.) +Unfortunately \optsand23 are far more problematic and need some +complex code to deal with awkward locations. + +If you know that your locations will always expand to a format +acceptable to your chosen \gls{indexingapp} then use the package +option \pkgopt[false]{esclocations} to bypass this operation. This setting +only affects \optsand23 as the problem doesn't arise with the other +indexing options. + +Both \gls{makeindex} and \gls{xindy} are fussy about the syntax of +the locations. In the case of \gls{makeindex}, only the numbering +system obtained with \cs{arabic}, \cs{roman}, \cs{Roman}, \cs{alph} +and \cs{Alph} or composites formed from them with the same separator +(set with \cs{glsSetCompositor}\marg{char}) are accepted. +(\gls{makeindex} won't accept an empty location.) In the case of +\gls{xindy}, you can define your own location classes, but if the +location contains a robust command then the leading backslash must +be escaped. The \sty{glossaries} package tries to do this, but it's +caught between two conflicting requirements: +\begin{enumerate} +\item The location must be fully expanded before \verb|\| can be +converted to \verb|\\| (there's no point converting \verb|\thepage| +to \verb|\\thepage|); +\item The page number can't be expanded until the deferred write +operation (so \verb|\c@page| mustn't expand in the previous step +but \verb|\the\c@page| mustn't be converted to \verb|\\the\\c@page| +and \verb|\number\c@page| mustn't be converted to +\verb|\\number\\c@page| etc). +\end{enumerate} +There's a certain amount of trickery needed to deal with this +conflict and the code requires the location to be in a form that +doesn't embed the counter's internal register in commands like +\cs{value}. For example, suppose you have a robust command called +\cs{tallynum} that takes a number as the argument and an expandable +command called \cs{tally} that converts a counter name into the +associated register or number to pass to \cs{tallynum}. Let's +suppose that this command is used to represent the page number: +\begin{verbatim} +\renewcommand{\thepage}{\tally{page}} +\end{verbatim} +Now let's suppose that a term is indexed at the beginning of page~2 +at the end of a paragraph that started on page~1. With \gls{xindy}, +the location \verb|\tally{page}| needs to be written to the file +as \verb|\\tallynum{2}|. If it's written as \verb|\tallynum{2}| then +\gls{xindy} will interpret \verb|\t| as the character \qt{t} +(which means the location would appear as \qt{tallynum2}). So +\sty{glossaries} tries to expand \cs{thepage} without expanding +\cs{c@page} and then escapes all the backslashes, except for the +page counter's internal command. The following definitions of +\cs{tally} will work: +\begin{itemize} +\item In the following, \cs{arabic} works as its internal command \cs{c@arabic} is +temporarily redefined to check for \cs{c@page}: +\begin{verbatim} +\newcommand{\tally}[1]{\tallynum{\arabic{#1}}} +\end{verbatim} + +\item The form \verb|\expandafter\the\csname c@|\meta{counter}\verb|\endcsname| +also works (provided \cs{the} is allowed to be temporarily redefined, +see below): +\begin{verbatim} +\newcommand{\tally}[1]{% + \tallynum{\expandafter\the\csname c@#1\endcsname}} +\end{verbatim} + +\item \verb|\expandafter\the\value|\marg{counter} now also works +(with the same condition as above): +\begin{verbatim} +\newcommand{\tally}[1]{\tallynum{\expandafter\the\value{#1}}} +\end{verbatim} + +\item Another variation that will work: +\begin{verbatim} +\newcommand{\tally}[1]{% + \expandafter\tallynum\expandafter{\the\csname c@#1\endcsname}} +\end{verbatim} + +\item and also: +\begin{verbatim} +\newcommand{\tally}[1]{\tallynum{\the\csname c@#1\endcsname}} +\end{verbatim} +\end{itemize} +The following \emph{don't work}: +\begin{itemize} +\item This definition leads to the premature expansion of \cs{c@page} +to \qt{1} when, in this case, it should be \qt{2}: +\begin{verbatim} +\newcommand{\tally}[1]{\tallynum{\the\value{#1}}} +\end{verbatim} +\item This definition leads to \verb|\\c@page| in the glossary file: +\begin{verbatim} +\newcommand{\tally}[1]{\tallynum{\csname c@#1\endcsname}} +\end{verbatim} +\end{itemize} +If you have a numbering system where +\verb|\|\meta{cs name}\verb|{page}| expands to +\verb|\|\meta{internal cs name}\cs{c@page} (for example, if +\verb|\tally{page}| expands to \verb|\tallynum\c@page|) then you +need to use: +\begin{definition}[\DescribeMacro\glsaddprotectedpagefmt] +\cs{glsaddprotectedpagefmt}\marg{internal cs name} +\end{definition} +Note that the backslash must be omitted from \meta{internal cs name} +and the corresponding command must be able to process a count +register as the (sole) argument. + +For example, suppose you have a style \texttt{samplenum} that is +implemented as follows: +\begin{verbatim} + \newcommand*{\samplenum}[1]{% + \expandafter\@samplenum\csname c@#1\endcsname} + \newcommand*{\@samplenum}[1]{\two@digits{#1}} + +\end{verbatim} +(That is, it displays the value of the counter as a two-digit +number.) Then to ensure the location is correct for entries in +page-spanning paragraphs, you need to do: +\begin{verbatim} +\glsaddprotectedpagefmt{@samplenum} +\end{verbatim} +(If you are using a different counter for the location, such as +\texttt{section} or \texttt{equation}, you don't need to worry about +this provided the inner command is expandable.) + +If the inner macro (as given by \verb|\|\meta{internal cs name}) contains +non-expandable commands then you may need to redefine +\cs{gls}\meta{internal cs name}\texttt{page} after using +\cs{glsaddprotectedpagefmt}\marg{internal cs name}. This command doesn't take any arguments +as \emph{the location is assumed to be given by \cs{c@page}} because +that's the only occasion this command should be used. For example, +suppose now my page counter format uses small caps Roman numerals: +\begin{verbatim} + \newcommand*{\samplenum}[1]{% + \expandafter\@samplenum\csname c@#1\endcsname} + \newcommand*{\@samplenum}[1]{\textsc{\romannumeral#1}} +\end{verbatim} +Again, the inner macro needs to be identified using: +\begin{verbatim} +\glsaddprotectedpagefmt{@samplenum} +\end{verbatim} +However, since \cs{textsc} isn't fully expandable, the location +is written to the file as \verb|\textsc {i}| (for page~1), +\verb|\textsc {ii}| (for page~2), etc. This format may cause a problem for +the \gls{indexingapp} (particularly for \gls{makeindex}). +To compensate for this, the \cs{gls}\meta{internal cs +name}\texttt{page} command may be redefined so that it expands to a +format that's acceptable to the \gls*{indexingapp}. For example: +\begin{verbatim} +\renewcommand*{\gls@samplenumpage}{\romannumeral\c@page} +\end{verbatim} +While this modification means that the \gls{numberlist} in the glossary +won't exactly match the format of the page numbers (displaying +lower case Roman numbers instead of small cap Roman numerals) +this method will at least work correctly for both \gls{makeindex} +and \gls{xindy}. If you are using \gls{xindy}, the following +definition: +\begin{verbatim} + \renewcommand*{\gls@samplenumpage}{% + \glsbackslash\string\textsc{\romannumeral\c@page}} +\end{verbatim} +combined with +\begin{verbatim} +\GlsAddXdyLocation{romansc}{:sep "\string\textsc\glsopenbrace" + "roman-numbers-lowercase" :sep "\glsclosebrace"} +\end{verbatim} +will now have lowercase Roman numerals in the location list +(see \sectionref{sec:xindyloc} for further details on that command). +Take care of the backslashes. The location (which ends up in +the ":locref" attribute) needs \verb|\\| but the location class +(identified with \cs{GlsAddXdyLocation}) just has a single +backslash. Note that this example will cause problems if your +locations should be hyperlinks. + +Another possibility that may work with both \gls{makeindex} and +\gls{xindy} is to redefine \cs{gls}\meta{internal cs +name}\texttt{page} (\cs{gls@samplenumpage} in this example) +to just expand to the decimal page number (\verb|\number\c@page|) and redefine +\ics{glsnumberformat} to change the displayed format: +\begin{verbatim} +\renewcommand*{\gls@samplenumpage}{\number\c@page} +\renewcommand*{\glsnumberformat}[1]{\textsc{\romannumeral#1}} +\end{verbatim} + +\begin{important} +If you redefine \cs{gls}\meta{internal cs name}\texttt{page}, +you must make sure that \cs{c@page} is expanded when it's written to +the file. (So don't, for example, hide \cs{c@page} inside a robust +command.) +\end{important} + +The mechanism that allows this to work temporarily redefines +\ics{the} and \ics{number} while it processes the location. If this +causes a problem you can disallow it using +\begin{definition}[\DescribeMacro\glswrallowprimitivemodsfalse] +\cs{glswrallowprimitivemodsfalse} +\end{definition} +but you will need to find some other way to ensure the location expands +correctly. + +\section{Range Formations} +\label{sec:ranges} + +Both \gls{makeindex} and \gls{xindy} (\optsand23) concatenate a +sequence of~3 or more consecutive pages into~a range. With +\gls*{xindy} (\opt3) you can vary the minimum sequence length using +\ics{GlsSetXdyMinRangeLength}\marg{n} where \meta{n} is either +an integer or the keyword \texttt{none} which indicates that there +should be no range formation (see \sectionref{sec:xindyloc} for +further details). + +\begin{important} +Note that \cs{GlsSetXdyMinRangeLength} must be used before +\ics{makeglossaries} and has no effect if \ics{noist} is used. +\end{important} + +With both \gls{makeindex} and \gls{xindy} (\optsand23), you can replace +the separator and the closing number in the range using: +\begin{definition}[\DescribeMacro{\glsSetSuffixF}] +\cs{glsSetSuffixF}\marg{suffix} +\end{definition} +\begin{definition}[\DescribeMacro{\glsSetSuffixFF}] +\cs{glsSetSuffixFF}\marg{suffix} +\end{definition} +where the former command specifies the suffix to use for a 2 page +list and the latter specifies the suffix to use for longer lists. +For example: +\begin{verbatim} +\glsSetSuffixF{f.} +\glsSetSuffixFF{ff.} +\end{verbatim} +Note that if you use \gls{xindy} (\opt3), you will also need to +set the minimum range length to 1 if you want to change these +suffixes: +\begin{verbatim} +\GlsSetXdyMinRangeLength{1} +\end{verbatim} +Note that if you use the \sty{hyperref} package, you will need +to use \ics{nohyperpage} in the suffix to ensure that the hyperlinks +work correctly. For example: +\begin{verbatim} +\glsSetSuffixF{\nohyperpage{f.}} +\glsSetSuffixFF{\nohyperpage{ff.}} +\end{verbatim} + +\begin{important} +Note that \cs{glsSetSuffixF} and \cs{glsSetSuffixFF} must be used +before \ics{makeglossaries} and have no effect if \ics{noist} is +used. +\end{important} + +It's also possible to concatenate a sequence of consecutive +locations into a range or have suffixes with \opt4, but with +\gls{bib2gls} these implicit ranges can't be merged with explicit +ranges (created with the \verb|(| and \verb|)| encaps). See +the \gls{bib2gls} manual for further details. + +\opt1 doesn't form ranges. However, with this option you +can iterate over an entry's \gls{numberlist} using: +\begin{definition}[\DescribeMacro\glsnumberlistloop] +\cs{glsnumberlistloop}\marg{label}\marg{handler cs}\marg{xr handler +cs} +\end{definition} +where \meta{label} is the entry's label and \meta{handler cs} is a +handler control sequence of the form: +\begin{definition} +\meta{handler cs}\marg{prefix}\marg{counter}\marg{format}\marg{location} +\end{definition} +where \meta{prefix} is the \sty{hyperref} prefix, \meta{counter} is +the name of the counter used for the location, \meta{format} is the +format used to display the location (e.g.\ \texttt{textbf}) +and \meta{location} is the location. The third argument is the +control sequence to use for any cross-references in the list. This +handler should have the syntax: +\begin{definition} +\meta{xr handler cs}\oarg{tag}\marg{xr list} +\end{definition} +where \meta{tag} is the cross-referenced text (e.g.\ \qt{see}) and +\meta{xr list} is a~comma-separated list of labels. (This actually +has a third argument but it's always empty when used with \opt1.) + +For example, if on page~12 +I~have used +\begin{verbatim} +\gls[format=textbf]{apple} +\end{verbatim} +and on page~18 I~have used +\begin{verbatim} +\gls[format=emph]{apple} +\end{verbatim} +then +\begin{verbatim} +\glsnumberlistloop{apple}{\myhandler} +\end{verbatim} +will be equivalent to: +\begin{verbatim} +\myhandler{}{page}{textbf}{12}% +\myhandler{}{page}{emph}{18}% +\end{verbatim} +There is a predefined handler that's used to display the +\gls{numberlist} in the glossary: +\begin{definition}[\DescribeMacro\glsnoidxdisplayloc] +\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location} +\end{definition} +The predefined handler used for the cross-references in the glossary is: +\begin{definition} +\cs{glsseeformat}\oarg{tag}\marg{xr list}\marg{location} +\end{definition} +which is described in \sectionref{sec:customxr}. + +\begin{important} +\cs{glsnumberlistloop} is not available for \optsand23. +\end{important} + +\section{Style Hook} +\label{sec:isthook} + +As from version 4.24, there's a hook that's used near the end of +\ics{writeist} before the file is closed. You can set the code +to be performed then using: +\begin{definition}[\DescribeMacro\GlsSetWriteIstHook] +\cs{GlsSetWriteIstHook}\marg{code} +\end{definition} +If you want the \meta{code} to write any information to the +file, you need to use +\begin{definition}[\DescribeMacro\glswrite] +\cs{write}\cs{glswrite}\marg{style information} +\end{definition} +Make sure you use the correct format within \meta{style +information}. For example, if you are using \app{makeindex}: +\begin{verbatim} +\GlsSetWriteIstHook{% + \write\glswrite{page_precedence "arnAR"}% + \write\glswrite{line_max 80}% +} +\end{verbatim} +This changes the page type precedence\index{page type precedence} and the maximum line length +used by \app{makeindex}. + +Remember that if you switch to \app{xindy}, this will no longer be +valid code. + +\chapter{Links to Glossary Entries} +\label{sec:glslink} + +Once you have defined a glossary entry using \ics{newglossaryentry} +(\sectionref{sec:newglosentry}) or \ics{newacronym} (see +\sectionref{sec:acronyms}), you can refer to that entry in the +document using one of the commands listed in +\sectionref{sec:gls-like} or \sectionref{sec:glstext-like}. The text +which appears at that point in the document when using one of these +commands is referred to as the \gls{linktext} (even if there are no +hyperlinks). These commands also add a line to an external file that +is used to generate the relevant entry in the glossary. This +information includes an associated location that is added to the +\gls{numberlist} for that entry. By default, the location refers to +the page number. For further information on number lists, see +\sectionref{sec:numberlists}. These external files need to be +post-processed by \gls{makeindex} or \gls{xindy} unless you have +chosen \optsor14. If you don't use \ics{makeglossaries} these external +files won't be created. (\optsand14 write the information to the +\filetype{.aux} file.) + +Note that repeated use of these commands for the same entry can +cause the \gls{numberlist} to become quite long, which may not be +particular helpful to the reader. In this case, you can use the +non-indexing commands described in \sectionref{sec:glsnolink} or +you can use the supplemental \gls{glossaries-extra} package, which +provides a means to suppress the automated indexing of the commands listed +in this chapter. + +\begin{important} +I strongly recommend that you don't use the commands +defined in this chapter in the arguments of sectioning or caption +commands or any other command that has a moving argument. + +Aside from problems with expansion issues, PDF bookmarks and +possible nested hyperlinks in the table of contents (or list of +whatever) any use of the commands described in \sectionref{sec:gls-like} +will have their \firstuseflag\ unset when they appear in the table +of contents (or list of whatever). +\end{important} + +The above warning is particularly important if you are using the +\styfmt{glossaries} package in conjunction with the \sty{hyperref} +package. Instead, use one of the \emph{expandable} commands listed in +\sectionref{sec:glsnolink} (such as \ics{glsentrytext} \emph{but +not} the non-expandable +case changing versions like \ics{Glsentrytext}). Alternatively, provide an +alternative via the optional argument to the sectioning\slash caption +command or use \sty{hyperref}'s \ics{texorpdfstring}. Examples: +\begin{verbatim} +\chapter{An overview of \glsentrytext{perl}} +\chapter[An overview of Perl]{An overview of \gls{perl}} +\chapter{An overview of \texorpdfstring{\gls{perl}}{Perl}} +\end{verbatim} +If you want to retain the formatting that's available through +commands like \cs{acrshort} (for example, if you are using one of +the small caps styles), then you might want to consider the +\gls{glossaries-extra} package which provides commands +for this purpose. + +If you want the \gls{linktext} to produce a hyperlink to the +corresponding entry details in the glossary, you should load the +\sty{hyperref} package \emph{before} the \styfmt{glossaries} +package. That's what I've done in this document, so if you see a +hyperlinked term, such as \gls{linktext}, you can click on the word +or phrase and it will take you to a brief description in this +document's glossary. + +\begin{important} +If you use the \sty{hyperref} package, I strongly recommend you use +\app{pdflatex} rather than \app{latex} to compile your document, if +possible. The DVI format of \LaTeX\ has limitations with the +hyperlinks that can cause a problem when used with the +\styfmt{glossaries} package. Firstly, the DVI format can't break a +hyperlink across a line whereas PDF\LaTeX\ can. This means that long +glossary entries (for example, the full form of an acronym) won't be +able to break across a line with the DVI format. Secondly, the DVI +format doesn't correctly size hyperlinks in subscripts or +superscripts. This means that if you define a term that may be used +as a subscript or superscript, if you use the DVI format, it won't +come out the correct size. + +These are limitations of the DVI format not of the \sty{glossaries} +package. +\end{important} + +It may be that you only want terms in certain glossaries to have +hyperlinks, but not for other glossaries. In this case, you can use the +package option \pkgopt{nohypertypes} to identify the glossary lists +that shouldn't have hyperlinked \gls{linktext}. See +\sectionref{sec:pkgopts-general} for further details. + +The way the \gls{linktext} is displayed depends on +\begin{definition}[\DescribeMacro{\glstextformat}] +\cs{glstextformat}\marg{text} +\end{definition} +For example, to make all \gls{linktext} appear in a sans-serif +font, do: +\begin{verbatim} +\renewcommand*{\glstextformat}[1]{\textsf{#1}} +\end{verbatim} +Further customisation can be done via \ics{defglsentryfmt} or by +redefining \ics{glsentryfmt}. See \sectionref{sec:glsdisplay} for +further details. + +Each entry has an associated conditional referred to as the +\firstuseflag. Some of the commands described in this chapter +automatically unset this flag and can also use it +to determine what text should be displayed. These types of commands +are the \glslike\ commands and are described in +\sectionref{sec:gls-like}. The commands that don't reference or change +the \firstuseflag\ are \glstextlike\ commands and are described +in \sectionref{sec:glstext-like}. See \sectionref{sec:glsunset} for +commands that unset (mark the entry as having been used) or reset +(mark the entry as not used) the \firstuseflag\ without referencing +the entries. + +The \glslike\ and \glstextlike\ commands all take a first +optional argument that is a comma-separated list of +\meta{key}=\meta{value} options, described below. They also have a +star-variant, which inserts \texttt{hyper=false} at the start of the +list of options and a plus-variant, which inserts +\texttt{hyper=true} at the start of the list of options. For example +\verb|\gls*{sample}| is the same as \verb|\gls[hyper=false]{sample}| +and \verb|\gls+{sample}| is the same as +\verb|\gls[hyper=true]{sample}|, whereas just \verb|\gls{sample}| +will use the default hyperlink setting which depends on a number of +factors (such as whether the entry is in a glossary that has been +identified in the \pkgopt{nohypertypes} list). You can override the +\gloskey[glslink]{hyper} key in the variant's optional argument, for +example, \verb|\gls*[hyper=true]{sample}| but this creates +redundancy and is best avoided. The \gls{glossaries-extra} package +provides the option to add a third custom variant. + +\begin{important} +Avoid nesting these commands. For example don't do +\cs{glslink}\marg{label}\texttt{\{\cs{gls}\marg{label2}\}} +as this is likely to cause problems. By implication, this +means that you should avoid using any of these commands within +the \gloskey{text}, \gloskey{first}, \gloskey{short} or +\gloskey{long} keys (or their plural equivalent) or any +other key that you plan to access through these commands. +(For example, the \gloskey{symbol} key if you intend to use +\cs{glssymbol}.) +\end{important} + +The keys listed below are available for the optional argument. +The \gls{glossaries-extra} package provides additional keys. +(See the \gls*{glossaries-extra} manual for further details.) +\begin{description} +\item[{\gloskey[glslink]{hyper}}] This is a boolean key which can +be used to enable\slash disable the hyperlink to the relevant entry +in the glossary. If this key is omitted, the value is determined by current +settings, as indicated above. For example, when used with a \glslike\ command, if this is the first +use and the \pkgopt[false]{hyperfirst} package option has been used, +then the default value is \texttt{hyper=false}. The hyperlink can be +forced on using \texttt{hyper=true} unless the hyperlinks have been +suppressed using \ics{glsdisablehyper}. You must load the +\sty{hyperref} package before the \sty{glossaries} package to +ensure the hyperlinks work. + +\item[{\gloskey[glslink]{format}}] This specifies how to format the +associated location number for this entry in the glossary. This +value is equivalent to the \gls{makeindex} encap value, and (as +with \ics{index}) the value needs to be the name of a command +\emph{without} the initial backslash. As with \ics{index}, the +characters \verb"(" and \verb")" can also be used to specify the +beginning and ending of a number range and they must be in matching +pairs. (For example, \verb|\gls[format={(}]{sample}| on one page +to start the range and later \verb|\gls[format={)}]{sample}| to close +the range.) Again as with \ics{index}, the command should be the +name of a command which takes an argument (which will be the +associated location). Be careful not to use a declaration (such as +\texttt{bfseries}) instead of a text block command (such as +\texttt{textbf}) as the effect is not guaranteed to be localised. If +you want to apply more than one style to a given entry (e.g.\ +\textbf{bold} and \emph{italic}) you will need to create a command +that applies both formats, e.g.\ +\begin{verbatim} +\newcommand*{\textbfem}[1]{\textbf{\emph{#1}}} +\end{verbatim} +and use that command. + +In this document, the standard formats refer to the standard text +block commands such as \ics{textbf} or \ics{emph} or any of the +commands listed in \tableref{tab:hyperxx}. You can combine a range +and format using \verb|(|\meta{format} to start the range and +\verb|)|\meta{format} to end the range. The \meta{format} part must +match. For example, \verb|format={(emph}| and \verb|format={)emph}|. + +\begin{important} +If you use \gls{xindy} instead of \gls{makeindex}, you +must specify any non-standard formats that you want to use +with the \gloskey[glslink]{format} key using +\ics{GlsAddXdyAttribute}\marg{name}. So if you use +\gls*{xindy} with the above example, you would need to add: +\begin{verbatim} +\GlsAddXdyAttribute{textbfem} +\end{verbatim} +See \sectionref{sec:xindy} for further details. +\end{important} + +If you are using hyperlinks and you want to change the font of the +hyperlinked location, don't use \ics{hyperpage} (provided by the +\sty{hyperref} package) as the locations may not refer to a page +number. Instead, the \styfmt{glossaries} package provides number +formats listed in \tableref{tab:hyperxx}. + +\begin{table}[htbp] +\caption{Predefined Hyperlinked Location Formats} +\label{tab:hyperxx} +\centering +\vskip\baselineskip +\begin{tabular}{ll} +\locfmt{hyperrm} & serif hyperlink\\ +\locfmt{hypersf} & sans-serif hyperlink\\ +\locfmt{hypertt} & monospaced hyperlink\\ +\locfmt{hyperbf} & bold hyperlink\\ +\locfmt{hypermd} & medium weight hyperlink\\ +\locfmt{hyperit} & italic hyperlink\\ +\locfmt{hypersl} & slanted hyperlink\\ +\locfmt{hyperup} & upright hyperlink\\ +\locfmt{hypersc} & small caps hyperlink\\ +\locfmt{hyperemph} & emphasized hyperlink +\end{tabular} +\par +\end{table} + +Note that if the \ics{hyperlink} command hasn't been defined, the +\texttt{hyper}\meta{xx} formats are equivalent to the analogous +\texttt{text}\meta{xx} font commands (and \texttt{hyperemph} is +equivalent to \texttt{emph}). If you want to make a new format, you +will need to define a command which takes one argument and use that. +For example, if you want the location number to be in a bold +sans-serif font, you can define a command called, say, +\ics{hyperbsf}: +\begin{verbatim} +\newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}} +\end{verbatim} +and then use \texttt{hyperbsf} as the value for the \gloskey{format} +key.\footnote{See also \ifpdf section~\ref*{sec:code:printglos} \fi +\qt{Displaying the glossary} in the documented code, +\texttt{glossaries-code.pdf}.} Remember that if you use \gls{xindy}, you +will need to add this to the list of location attributes: +\begin{verbatim} +\GlsAddXdyAttribute{hyperbsf} +\end{verbatim} + +\item[{\gloskey[glslink]{counter}}] This specifies which counter +to use for this location. This overrides the default counter +used by this entry. (See also \sectionref{sec:numberlists}.) + +\item[{\gloskey[glslink]{local}}] This is a boolean key that only +makes a difference when used with \glslike\ commands that change the +entry's \gls{firstuseflag}. If \texttt{local=true}, the change to +the \gls*{firstuseflag} will be localised to the current scope. The +default is \texttt{local=false}. + +\end{description} + +\begin{important} +The \gls{linktext} isn't scoped by default. Any unscoped +declarations in the \gls{linktext} may affect subsequent text. +\end{important} + +\section{The \cs{gls}-Like Commands (First Use Flag Queried)} +\label{sec:gls-like} + +This section describes the commands that unset (mark as used) the \firstuseflag\ on +completion, and in most cases they use the current state of the flag +to determine the text to be displayed. As described above, these +commands all have a star-variant (\texttt{hyper=false}) and +a plus-variant (\texttt{hyper=true}) and have an +optional first argument that is a \meta{key}=\meta{value} list. + +These commands use \ics{glsentryfmt} or the equivalent definition provided by +\ics{defglsentryfmt} to determine the automatically generated text +and its format (see \sectionref{sec:glsdisplay}). + +Apart from \ics{glsdisp}, the commands described in this section +also have a \emph{final} optional argument \meta{insert} which may +be used to insert material into the automatically generated text. + +\begin{important} +Since the commands have a final optional argument, take care if +you actually want to display an open square bracket after the command +when the final optional argument is absent. Insert an empty set of +braces \verb|{}| immediately before the opening square bracket to +prevent it from being interpreted as the final argument. For +example: +\begin{verbatim} +\gls{sample} {}[Editor's comment] +\end{verbatim} + +Don't use any of the \glslike\ or \glstextlike\ commands in the +\meta{insert} argument. +\end{important} + +Take care using these commands within commands or environments that +are processed multiple times as this can confuse the first use flag +query and state change. This includes frames with overlays in +\cls{beamer} and the \envfmt{tabularx} environment provided by \sty{tabularx}. +The \styfmt{glossaries} package automatically deals with this issue +in \sty{amsmath}'s \envfmt{align} environment. You can apply a patch +to \sty{tabularx} by placing the following command (new to v4.28) in +the preamble: +\begin{definition}[\DescribeMacro\glspatchtabularx] +\cs{glspatchtabularx} +\end{definition} +This does nothing if \sty{tabularx} hasn't been loaded. There's no +patch available for \cls{beamer}. See \sectionref{sec:glsunset} for +more details. + +\begin{definition}[\DescribeMacro{\gls}] +\cs{gls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This command typically determines the \gls{linktext} from the values +of the \gloskey{text} or \gloskey{first} keys supplied when the +entry was defined using \ics{newglossaryentry}. However, if the +entry was defined using \ics{newacronym} and \ics{setacronymstyle} was +used, then the \gls*{linktext} will usually be determined from the \gloskey{long} or +\gloskey{short} keys. + +There are two upper case variants: +\begin{definition}[\DescribeMacro{\Gls}] +\cs{Gls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +and +\begin{definition}[\DescribeMacro{\GLS}] +\cs{GLS}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +which make the first letter of the link text or all the link text +upper case, respectively. For the former, the uppercasing of the +first letter is performed by \ics{makefirstuc}. + +\begin{important} +The first letter uppercasing command \cs{makefirstuc} has +limitations which must be taken into account if you use \cs{Gls} or +any of the other commands that convert the first letter to +uppercase. +\end{important} +The upper casing is performed as follows: +\begin{itemize} +\item If the first thing in the \gls{linktext} is a command follow +by a group, the upper casing is performed on the first object of the +group. For example, if an entry has been defined as +\begin{verbatim} +\newglossaryentry{sample}{ + name={\emph{sample} phrase}, + sort={sample phrase}, + description={an example}} +\end{verbatim} +Then \cs{Gls}\verb|{sample}| will set the \gls{linktext} +to\footnote{I've used \cs{MakeUppercase} in all the examples for clarity, but it +will actually use \cs{mfirstucMakeUppercase}.} +\begin{verbatim} +\emph{\MakeUppercase sample} phrase +\end{verbatim} +which will appear as \emph{\MakeUppercase sample} phrase. + +\item If the first thing in the \gls{linktext} isn't a command or is +a command but isn't followed by a group, then the upper casing will +be performed on that first thing. For example, if an entry has been +defined as: +\begin{verbatim} +\newglossaryentry{sample}{ + name={\oe-ligature}, + sort={oe-ligature}, + description={an example} +} +\end{verbatim} +Then \cs{Gls}\verb|{sample}| will set the \gls{linktext} to +\begin{verbatim} +\MakeUppercase \oe-ligature +\end{verbatim} +which will appear as \MakeUppercase \oe-ligature. + +\item If you have \sty{mfirstuc} v2.01 or above, an extra case is +added. If the first thing is \cs{protect} it will be discarded and +the above rules will then be tried. + +\end{itemize} +(Note the use of the \gloskey{sort} key in the above examples.) + +There are hundreds of \LaTeX\ packages that altogether define +thousands of commands with various syntax and it's impossible for +\sty{mfirstuc} to take them all into account. The above rules are quite +simplistic and are designed for \gls{linktext} that starts with +a~text-block command (such as \cs{emph}) or a command that produces +a character (such as \cs{oe}). This means that if your \gls{linktext} +starts with something that doesn't adhere to \sty{mfirstuc}'s assumptions +then things are likely to go wrong. + +For example, starting with a math-shift symbol: +\begin{verbatim} +\newglossaryentry{sample}{ + name={$a$}, + sort={a}, + description={an example} +} +\end{verbatim} +This falls into case~2 above, so the \gls{linktext} will be set to +\begin{verbatim} +\MakeUppercase $a$ +\end{verbatim} +This attempts to uppercase the math-shift \verb|$|, which will go +wrong. In this case it's not appropriate to perform any +case-changing, but it may be that you want to use \cs{Gls} +programmatically without checking if the text contains any maths. +In this case, the simplest solution is to insert an empty brace at +the start: +\begin{verbatim} +\newglossaryentry{sample}{ + name={{}$a$}, + sort={a}, + description={an example} +} +\end{verbatim} +Now the \gls{linktext} will be set to +\begin{verbatim} +\MakeUppercase{}$a$ +\end{verbatim} +and the \cs{uppercase} becomes harmless. + +Another issue occurs when the \gls{linktext} starts with a command +followed by an argument (case~1) but the argument is a label, +identifier or something else that shouldn't have a case-change. +A common example is when the \gls{linktext} starts with one of the +commands described in this chapter. (But you haven't done that, have +you? What with the warning not to do it at the beginning of the chapter.) +Or when the \gls{linktext} starts with one of the non-linking +commands described in \sectionref{sec:glsnolink}. For example: +\begin{verbatim} +\newglossaryentry{sample}{name={sample},description={an example}} +\newglossaryentry{sample2}{ + name={\glsentrytext{sample} two}, + sort={sample two}, + description={another example} + } +\end{verbatim} +Now the \gls{linktext} will be set to: +\begin{verbatim} +\glsentrytext{\MakeUppercase sample} two +\end{verbatim} +This will generate an error because there's no entry with the label +given by \verb|\MakeUppercase sample|. The best solution here is to +write the term out in the \gloskey{text} field and use the command +in the \gloskey{name} field. If you don't use \cs{glsname} anywhere +in your document, you can use \cs{gls} in the \gloskey{name} field: +\begin{verbatim} +\newglossaryentry{sample}{name={sample},description={an example}} +\newglossaryentry{sample2}{ + name={\gls{sample} two}, + sort={sample two}, + text={sample two}, + description={another example} + } +\end{verbatim} + +If the \gls{linktext} starts with a command that has an optional +argument or with multiple arguments where the actual text isn't in +the first argument, then \cs{makefirstuc} will also fail. For +example: +\begin{verbatim} +\newglossaryentry{sample}{ + name={\textcolor{blue}{sample} phrase}, + sort={sample phrase}, + description={an example}} +\end{verbatim} +Now the \gls{linktext} will be set to: +\begin{verbatim} +\textcolor{\MakeUppercase blue}{sample} phrase +\end{verbatim} +This won't work because \verb|\MakeUppercase blue| isn't a recognised +colour name. In this case you will have to define a helper command where +the first argument is the text. For example: +\begin{verbatim} +\newglossaryentry{sample}{ +\newcommand*{\blue}[1]{\textcolor{blue}{#1}} + name={\blue{sample} phrase}, + sort={sample phrase}, + description={an example}} +\end{verbatim} +In fact, since the whole design ethos of \LaTeX\ is the separation +of content and style, it's better to use a semantic command. For +example: +\begin{verbatim} +\newglossaryentry{sample}{ +\newcommand*{\keyword}[1]{\textcolor{blue}{#1}} + name={\keyword{sample} phrase}, + sort={sample phrase}, + description={an example}} +\end{verbatim} +For further details see the \sty{mfirstuc} user manual. + +There are plural forms that are analogous to \cs{gls}: +\begin{definition}[\DescribeMacro{\glspl}] +\cs{glspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\Glspl}] +\cs{Glspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSpl}] +\cs{GLSpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +These typically determine the link text from the \gloskey{plural} or +\gloskey{firstplural} keys supplied when the entry was +defined using \ics{newglossaryentry} or, if the entry is an +abbreviation and \cs{setacronymstyle} was used, from the \gloskey{longplural} or +\gloskey{shortplural} keys. + +\begin{important} +Be careful when you use glossary entries in math mode especially if you +are using \sty{hyperref} as it can affect the spacing of subscripts and +superscripts. For example, suppose you have defined the following +entry: +\begin{verbatim} +\newglossaryentry{Falpha}{name={F_\alpha}, +description=sample} +\end{verbatim} +and later you use it in math mode: +\begin{verbatim} +$\gls{Falpha}^2$ +\end{verbatim} +This will result in $F_\alpha{}^2$ instead of $F_\alpha^2$. In this +situation it's best to bring the superscript into the hyperlink using +the final \meta{insert} optional argument: +\begin{verbatim} +$\gls{Falpha}[^2]$ +\end{verbatim} +\end{important} + +\begin{definition}[\DescribeMacro{\glsdisp}] +\cs{glsdisp}\oarg{options}\marg{label}\marg{link text} +\end{definition} +This behaves in the same way as the above commands, except +that the \meta{link text} is explicitly set. There's no final +optional argument as any inserted material can be added to the +\meta{link text} argument. + +\begin{important} +Don't use any of the \glslike\ or \glstextlike\ commands in the +\meta{link text} argument of \cs{glsdisp}. +\end{important} + +\section{The \cs{glstext}-Like Commands (First Use Flag Not Queried)} +\label{sec:glstext-like} + +This section describes the commands that don't change or reference +the \firstuseflag. As described above, these commands all have a +star-variant (\texttt{hyper=false}) and a plus-variant +(\texttt{hyper=true}) and have an optional first argument +that is a \meta{key}=\meta{value} list. These commands also don't +use \ics{glsentryfmt} or the equivalent definition provided by +\ics{defglsentryfmt} (see \sectionref{sec:glsdisplay}). +Additional commands for abbreviations are described in +\sectionref{sec:acronyms}. + +Apart from \ics{glslink}, the commands described in this section +also have a \emph{final} optional argument \meta{insert} which may +be used to insert material into the automatically generated text. +See the caveat above in \sectionref{sec:gls-like}. + +\begin{definition}[\DescribeMacro{\glslink}] +\cs{glslink}\oarg{options}\marg{label}\marg{link text} +\end{definition} +This command explicitly sets the \gls{linktext} as given in the +final argument. + +\begin{important} +Don't use any of the \glslike\ or \glstextlike\ commands in the +argument of \cs{glslink}. By extension, this means that you can't +use them in the value of fields that are used to form +\gls{linktext}. +\end{important} + +\begin{definition}[\DescribeMacro{\glstext}] +\cs{glstext}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This command always uses the value of the \gloskey{text} key as the +\gls{linktext}. + +There are also analogous commands: +\begin{definition}[\DescribeMacro{\Glstext}] +\cs{Glstext}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLStext}] +\cs{GLStext}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +These convert the first character or all the characters to +uppercase, respectively. See the note on \cs{Gls} above for details +on the limitations of converting the first letter to upper case. + +There's no equivalent command for title-casing, but you +can use the more generic command \ics{glsentrytitlecase} +in combination with \cs{glslink}. For example: +\begin{verbatim} +\glslink{sample}{\glsentrytitlecase{sample}{text}} +\end{verbatim} +(See \sectionref{sec:glsnolink}.) + +\begin{definition}[\DescribeMacro{\glsfirst}] +\cs{glsfirst}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This command always uses the value of the \gloskey{first} key as the +\gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsfirst}] +\cs{Glsfirst}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSfirst}] +\cs{GLSfirst}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{important} +The value of the \gloskey{first} key (and \gloskey{firstplural} key) +doesn't necessarily match the text produced by \ics{gls} (or \ics{glspl}) on +\firstuse\ as the \gls{linktext} used by \ics{gls} may be modified +through commands like \ics{defglsentry}. (Similarly, the value of the +\gloskey{text} and \gloskey{plural} keys don't necessarily match +the \gls*{linktext} used by \cs{gls} or \cs{glspl} on subsequent +use.) +\end{important} + +\begin{definition}[\DescribeMacro{\glsplural}] +\cs{glsplural}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This command always uses the value of the \gloskey{plural} key as the +\gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsplural}] +\cs{Glsplural}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSplural}] +\cs{GLSplural}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{definition}[\DescribeMacro{\glsfirstplural}] +\cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This command always uses the value of the \gloskey{firstplural} key as the +\gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsfirstplural}] +\cs{Glsfirstplural}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSfirstplural}] +\cs{GLSfirstplural}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{definition}[\DescribeMacro{\glsname}] +\cs{glsname}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This command always uses the value of the \gloskey{name} key as the +\gls{linktext}. Note that this may be different from the values of +the \gloskey{text} or \gloskey{first} keys. In general it's better +to use \cs{glstext} or \cs{glsfirst} instead of \cs{glsname}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsname}] +\cs{Glsname}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSname}] +\cs{GLSname}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{important} +In general it's best to avoid \cs{Glsname} with acronyms. Instead, +consider using \cs{Acrlong}, \cs{Acrshort} or \cs{Acrfull}. +\end{important} + +\begin{definition}[\DescribeMacro{\glssymbol}] +\cs{glssymbol}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This command always uses the value of the \gloskey{symbol} key as the +\gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glssymbol}] +\cs{Glssymbol}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSsymbol}] +\cs{GLSsymbol}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{definition}[\DescribeMacro{\glsdesc}] +\cs{glsdesc}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This command always uses the value of the \gloskey{description} key as the +\gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsdesc}] +\cs{Glsdesc}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSdesc}] +\cs{GLSdesc}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +If you want the title case version you can use +\begin{verbatim} +\glslink{sample}{\glsentrytitlecase{sample}{desc}} +\end{verbatim} + +\begin{definition}[\DescribeMacro{\glsuseri}] +\cs{glsuseri}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This command always uses the value of the +\gloskey{user1} key as the \gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsuseri}] +\cs{Glsuseri}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSuseri}] +\cs{GLSuseri}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{definition}[\DescribeMacro{\glsuserii}] +\cs{glsuserii}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +This command always uses the value of the +\gloskey{user2} key as the \gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsuserii}] +\cs{Glsuserii}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSuserii}] +\cs{GLSuserii}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{definition}[\DescribeMacro{\glsuseriii}] +\cs{glsuseriii}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +This command always uses the value of the +\gloskey{user3} key as the \gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsuseriii}] +\cs{Glsuseriii}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSuseriii}] +\cs{GLSuseriii}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{definition}[\DescribeMacro{\glsuseriv}] +\cs{glsuseriv}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +This command always uses the value of the +\gloskey{user4} key as the \gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsuseriv}] +\cs{Glsuseriv}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSuseriv}] +\cs{GLSuseriv}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{definition}[\DescribeMacro{\glsuserv}] +\cs{glsuserv}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +This command always uses the value of the +\gloskey{user5} key as the \gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsuserv}] +\cs{Glsuserv}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSuserv}] +\cs{GLSuserv}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\begin{definition}[\DescribeMacro{\glsuservi}] +\cs{glsuservi}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +This command always uses the value of the +\gloskey{user6} key as the \gls{linktext}. + +There are also analogous uppercasing commands: +\begin{definition}[\DescribeMacro{\Glsuservi}] +\cs{Glsuservi}\oarg{options}\marg{text}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\GLSuservi}] +\cs{GLSuservi}\oarg{options}\marg{text}\oarg{insert} +\end{definition} + +\section{Changing the format of the link text} +\label{sec:glsdisplay} + +The default format of the \gls{linktext} for the \glslike\ commands +is governed by\footnote{\ics{glsdisplayfirst} and \ics{glsdisplay} are now +deprecated. Backwards compatibility should be preserved but +you may need to use the \pkgopt{compatible-3.07} option}: +\begin{definition}[\DescribeMacro{\glsentryfmt}] +\cs{glsentryfmt} +\end{definition} +This may be redefined but if you only want the change the display style +for a given glossary, then you need to use +\begin{definition}[\DescribeMacro{\defglsentryfmt}] +\cs{defglsentryfmt}\oarg{type}\marg{definition} +\end{definition} +instead of redefining \cs{glsentryfmt}. The optional first argument +\meta{type} is the glossary type. This defaults to +\ics{glsdefaulttype} if omitted. The second argument is the +entry format definition. + +\begin{important} +Note that \cs{glsentryfmt} is the default display format for +entries. Once the display format has been changed for an individual +glossary using \ics{defglsentryfmt}, redefining \cs{glsentryfmt} +won't have an effect on that glossary, you must instead use +\cs{defglsentryfmt} again. Note that glossaries that have +been identified as lists of acronyms (via the package option +\pkgopt{acronymlists} or the command \ics{DeclareAcronymList}, +see \sectionref{sec:pkgopts-acronym}) use +\cs{defglsentryfmt} to set their display style. +\end{important} + +Within the \meta{definition} argument of \cs{defglsentryfmt}, or if you +want to redefine \cs{glsentryfmt}, you may use the following +commands: + +\begin{definition}[\DescribeMacro{\glslabel}] +\cs{glslabel} +\end{definition} +This is the label of the entry being referenced. As from version +4.08, you can also access the glossary entry type using: +\begin{definition}[\DescribeMacro{\glstype}] +\cs{glstype} +\end{definition} +This is defined using \ics{edef} so the replacement text is the +actual glossary type rather than \verb|\glsentrytype{\glslabel}|. + +\begin{definition}[\DescribeMacro{\glscustomtext}] +\cs{glscustomtext} +\end{definition} +This is the custom text supplied in \cs{glsdisp}. It's always empty +for \ics{gls}, \ics{glspl} and their upper case variants. (You can +use \sty{etoolbox}'s \cs{ifdefempty} to determine if +\cs{glscustomtext} is empty.) + +\begin{definition}[\DescribeMacro{\glsinsert}] +\cs{glsinsert} +\end{definition} +The custom text supplied in the final optional argument to \cs{gls}, +\cs{glspl} and their upper case variants. + +\begin{definition}[\DescribeMacro{\glsifplural}] +\cs{glsifplural}\marg{true text}\marg{false text} +\end{definition} +If \cs{glspl}, \cs{Glspl} or \cs{GLSpl} was used, this command does +\meta{true text} otherwise it does \meta{false text}. + +\begin{definition}[\DescribeMacro{\glscapscase}] +\cs{glscapscase}\marg{no case}\marg{first uc}\marg{all caps} +\end{definition} +If \cs{gls}, \cs{glspl} or \cs{glsdisp} were used, this does \meta{no +case}. If \cs{Gls} or \cs{Glspl} were used, this does \meta{first +uc}. If \cs{GLS} or \cs{GLSpl} were used, this does \meta{all caps}. + +\begin{definition}[\DescribeMacro\glsifhyperon] +\cs{glsifhyperon}\marg{hyper true}\marg{hyper false} +\end{definition} +This will do \meta{hyper true} if the hyperlinks are on for the +current reference, otherwise it will do \meta{hyper false}. The +hyperlink may be off even if it wasn't explicitly switched off with +the \gloskey[glslink]{hyper} key or the use of a starred command. +It may be off because the \sty{hyperref} package hasn't been loaded +or because \ics{glsdisablehyper} has been used or because the entry +is in a glossary type that's had the hyperlinks switched off (using +\pkgopt{nohypertypes}) or because it's the \firstuse\ and the +hyperlinks have been suppressed on first use. + +Note that \ics{glsifhyper} is now deprecated. +If you want to know if the command used to reference +this entry was used with the star or plus variant, you can use: +\begin{definition}[\DescribeMacro\glslinkvar] +\cs{glslinkvar}\marg{unmodified}\marg{star}\marg{plus} +\end{definition} +This will do \meta{unmodified} if the unmodified version was used, +or will do \meta{star} if the starred version was used, or +will do \meta{plus} if the plus version was used. +Note that this doesn't take into account if the +\gloskey[glslink]{hyper} key was used to override the default +setting, so this command shouldn't be used to guess whether or not +the hyperlink is on for this reference. + +Note that you can also use commands such as \ics{ifglsused} within +the definition of \cs{glsentryfmt} (see \sectionref{sec:glsunset}). + +The commands \ics{glslabel}, \ics{glstype}, \ics{glsifplural}, +\ics{glscapscase}, \ics{glscustomtext} and \ics{glsinsert} are +typically updated at the start of the \glslike\ and \glstextlike\ +commands so they can usually be accessed in the hook user commands, +such as \ics{glspostlinkhook} and \ics{glslinkpostsetkeys}. + +\begin{important} +This means that using commands like \ics{gls} within the fields +that are accessed using the \glslike\ or \glstextlike\ commands +(such as the \gloskey{first}, \gloskey{text}, \gloskey{long} +or \gloskey{short} keys) will cause a problem. The entry formatting +performed by \cs{glsentryfmt} and related commands isn't scoped +(otherwise if would cause problems for \cs{glspostlinkhook} which +may need to look ahead as well as look behind). +This means that any nested commands will, at the very least, change +the label stored in \cs{glslabel}. +\end{important} + +If you only want to make minor modifications to \cs{glsentryfmt}, +you can use +\begin{definition}[\DescribeMacro{\glsgenentryfmt}] +\cs{glsgenentryfmt} +\end{definition} +This uses the above commands to display just the \gloskey{first}, +\gloskey{text}, \gloskey{plural} or \gloskey{firstplural} keys +(or the custom text) with the insert text appended. + +Alternatively, if want to change the entry format for abbreviations +(defined via \ics{newacronym}) you can use: +\begin{definition}[\DescribeMacro{\glsgenacfmt}] +\cs{glsgenacfmt} +\end{definition} +This uses the values from the \gloskey{long}, \gloskey{short}, +\gloskey{longplural} and \gloskey{shortplural} keys, rather than +using the \gloskey{text}, \gloskey{plural}, \gloskey{first} +and \gloskey{firstplural} keys. The first use singular text is obtained via: +\begin{definition}[\DescribeMacro{\genacrfullformat}] +\cs{genacrfullformat}\marg{label}\marg{insert} +\end{definition} +instead of from the \gloskey{first} key, and the first use plural +text is obtained via: +\begin{definition}[\DescribeMacro{\genplacrfullformat}] +\cs{genplacrfullformat}\marg{label}\marg{insert} +\end{definition} +instead of from the \gloskey{firstplural} key. +In both cases, \meta{label} is the entry's label and \meta{insert} +is the insert text provided in the final optional argument of +commands like \ics{gls}. The default behaviour is to do the long +form (or plural long form) followed by \meta{insert} and a~space and the short form (or plural +short form) in parentheses, where the short form is in the argument +of \ics{firstacronymfont}. There are also first letter upper case +versions: +\begin{definition}[\DescribeMacro{\Genacrfullformat}] +\cs{Genacrfullformat}\marg{label}\marg{insert} +\end{definition} +and +\begin{definition}[\DescribeMacro{\Genplacrfullformat}] +\cs{Genplacrfullformat}\marg{label}\marg{insert} +\end{definition} +By default these perform a protected expansion on their no-case-change +equivalents and then use \ics{makefirstuc} to convert the first +character to upper case. If there are issues caused by this +expansion, you will need to redefine those commands to explicitly +use commands like \ics{Glsentrylong} (which is what the predefined +acronym styles, such as \acrstyle{long-short}, do). Otherwise, you +only need to redefine \ics{genacrfullformat} and +\ics{genplacrfullformat} to change the behaviour of +\ics{glsgenacfmt}. See \sectionref{sec:acronyms} for further details +on changing the style of acronyms. + +\begin{important} +Note that \cs{glsentryfmt} (or the formatting given by \cs{defglsentryfmt}) +is not used by the \glstextlike\ commands. +\end{important} + +As from version 4.16, both the \glslike\ and \glstextlike\ commands +use +\begin{definition}[\DescribeMacro\glslinkpostsetkeys] +\cs{glslinkpostsetkeys} +\end{definition} +after the \meta{options} are set. This macro does nothing by default +but can be redefined. (For example, to switch off the hyperlink +under certain conditions.) This version also introduces +\begin{definition}[\DescribeMacro\glspostlinkhook] +\cs{glspostlinkhook} +\end{definition} +which is done after the link text has been displayed and also +\emph{after} the \firstuseflag\ has been unset (see +example~\ref{ex:dotabbr}). + +\begin{example}{Custom Entry Display in Text}{ex:customfmt} +Suppose you want a glossary of measurements and +units, you can use the \gloskey{symbol} key to store the unit: +\begin{verbatim} +\newglossaryentry{distance}{name=distance, +description={The length between two points}, +symbol={km}} +\end{verbatim} +and now suppose you want \verb|\gls{distance}| to produce +\qt{distance (km)} on \firstuse, then you can redefine +\ics{glsentryfmt} as follows: +\begin{verbatim} +\renewcommand*{\glsentryfmt}{% + \glsgenentryfmt + \ifglsused{\glslabel}{}{\space (\glsentrysymbol{\glslabel})}% +} +\end{verbatim} + +(Note that I've used \ics{glsentrysymbol} rather than \ics{glssymbol} +to avoid nested hyperlinks.) + +Note also that all of the \gls{linktext} will be formatted according +to \ics{glstextformat} (described earlier). So if you do, say: +\begin{verbatim} +\renewcommand{\glstextformat}[1]{\textbf{#1}} +\renewcommand*{\glsentryfmt}{% + \glsgenentryfmt + \ifglsused{\glslabel}{}{\space(\glsentrysymbol{\glslabel})}% +} +\end{verbatim} +then \verb|\gls{distance}| will produce \qt{\textbf{distance (km)}}. + +For a complete document, see the sample file \samplefile{-entryfmt}. +\end{example} + +\begin{example}{Custom Format for Particular Glossary}{ex:defglsentryfmt} +Suppose you have created a new glossary called +\texttt{notation} and you want to change the way the entry is +displayed on \firstuse\ so that it includes the symbol, you can do: +\begin{verbatim} +\defglsentryfmt[notation]{\glsgenentryfmt + \ifglsused{\glslabel}{}{\space + (denoted \glsentrysymbol{\glslabel})}} +\end{verbatim} +Now suppose you have defined an entry as follows: +\begin{verbatim} +\newglossaryentry{set}{type=notation, + name=set, + description={A collection of objects}, + symbol={$S$} +} +\end{verbatim} +The \glslink{firstuse}{first time} you reference this entry it will be displayed as: +\qt{set (denoted $S$)} (assuming \ics{gls} was used). + +Alternatively, if you expect all the symbols to be set in math mode, +you can do: +\begin{verbatim} +\defglsentryfmt[notation]{\glsgenentryfmt + \ifglsused{\glslabel}{}{\space + (denoted $\glsentrysymbol{\glslabel}$)}} +\end{verbatim} +and define entries like this: +\begin{verbatim} +\newglossaryentry{set}{type=notation, + name=set, + description={A collection of objects}, + symbol={S} +} +\end{verbatim} +\end{example} + +Remember that if you use the \gloskey{symbol} key, you need to use a +glossary style that displays the symbol, as many of the styles +ignore it. + +\section{Enabling and disabling hyperlinks to glossary entries} +\label{sec:disablehyperlinks} + +If you load the \sty{hyperref} or \sty{html} packages prior to +loading the \styfmt{glossaries} package, the \glslike\ and +\glstextlike\ commands will automatically have hyperlinks +to the relevant glossary entry, unless the \gloskey[glslink]{hyper} +option has been switched off (either explicitly or through +implicit means, such as via the \pkgopt{nohypertypes} package option). + +You can disable or enable links using: +\begin{definition}[\DescribeMacro{\glsdisablehyper}] +\cs{glsdisablehyper} +\end{definition} +and +\begin{definition}[\DescribeMacro{\glsenablehyper}] +\cs{glsenablehyper} +\end{definition} +respectively. The effect can be localised by placing the commands +within a group. Note that you should only use \cs{glsenablehyper} +if the commands \ics{hyperlink} and \ics{hypertarget} have been +defined (for example, by the \sty{hyperref} package). + +You can disable just the \gls{firstuse} links using the package +option \pkgopt[false]{hyperfirst}. Note that this option only +affects the \glslike\ commands that recognise the \firstuseflag. + +\begin{example}{First Use With Hyperlinked Footnote Description}{ex:hyperdesc} +Suppose I want the \gls*{firstuse} to have a hyperlink to the +description in a footnote instead of hyperlinking to the relevant +place in the glossary. First I need to disable the hyperlinks on +first use via the package option \pkgopt[false]{hyperfirst}: +\begin{verbatim} +\usepackage[hyperfirst=false]{glossaries} +\end{verbatim} +Now I need to redefine \ics{glsentryfmt} (see +\sectionref{sec:glsdisplay}): +\begin{verbatim} +\renewcommand*{\glsentryfmt}{% + \glsgenentryfmt + \ifglsused{\glslabel}{}{\footnote{\glsentrydesc{\glslabel}}}% +} +\end{verbatim} + +Now the first use won't have hyperlinked text, but will be followed +by a footnote. +See the sample file \samplefile{-FnDesc} for a complete document. +\end{example} + +Note that the \pkgopt{hyperfirst} option applies to all defined glossaries. It +may be that you only want to disable the hyperlinks on +\gls{firstuse} for glossaries that have a different form on +\gls*{firstuse}. This can be achieved by noting that since the +entries that require hyperlinking for all instances have identical +first and subsequent text, they can be unset via \ics{glsunsetall} +(see \sectionref{sec:glsunset}) so that the \pkgopt{hyperfirst} +option doesn't get applied. + +\begin{example}{Suppressing Hyperlinks on First Use Just For +Acronyms}{ex:hyperfirst} +Suppose I want to suppress the hyperlink on \gls{firstuse} for +acronyms but not for entries in the main glossary. I~can load +the \styfmt{glossaries} package using: +\begin{verbatim} +\usepackage[hyperfirst=false,acronym]{glossaries} +\end{verbatim} +Once all glossary entries have been defined I~then do: +\begin{verbatim} +\glsunsetall[main] +\end{verbatim} + +\end{example} + +For more complex requirements, you might find it easier to switch +off all hyperlinks via \ics{glsdisablehyper} and put the hyperlinks +(where required) within the definition of \ics{glsentryfmt} (see +\sectionref{sec:glsdisplay}) via \ics{glshyperlink} (see +\sectionref{sec:glsnolink}). + +\begin{example}{Only Hyperlink in Text Mode Not Math +Mode}{ex:nomathhyper} +This is a bit of a contrived example, but suppose, for some reason, +I only want the \glslike\ commands to have +hyperlinks when used in text mode, but not in math mode. I~can do +this by adding the glossary to the list of nohypertypes and redefining +\ics{glsentryfmt}: +\begin{verbatim} +\GlsDeclareNoHyperList{main} + +\renewcommand*{\glsentryfmt}{% + \ifmmode + \glsgenentryfmt + \else + \glsifhyperon + {\glsgenentryfmt}% hyperlink already on + {\glshyperlink[\glsgenentryfmt]{\glslabel}}% + \fi +} +\end{verbatim} +Note that this doesn't affect the \glstextlike\ commands, which will +have the hyperlinks off unless they're forced on using the plus +variant. + +See the sample file \samplefile{-nomathhyper} for a complete +document. +\end{example} + +\begin{example}{One Hyper Link Per Entry Per Chapter}{ex:chap-hyperfirst} +Here's a more complicated example that will only have the hyperlink +on the first time an entry is used per chapter. This doesn't involve +resetting the \firstuseflag. Instead it adds a~new key using +\ics{glsaddstoragekey} (see \sectionref{sec:glsaddstoragekey}) that +keeps track of the chapter number that the entry was last used in: +\begin{verbatim} +\glsaddstoragekey{chapter}{0}{\glschapnum} +\end{verbatim} +This creates a new user command called \cs{glschapnum} that's +analogous to \cs{glsentrytext}. The default value for this key is~0. +I~then define my glossary entries as usual. + +Next I redefine the hook \ics{glslinkpostsetkeys} +(see \sectionref{sec:glsdisplay}) so that it determines the current +chapter number (which is stored in \cs{currentchap} using +\cs{edef}). This value is then compared with the value of the +entry's \texttt{chapter} key that I defined earlier. If they're the +same, this entry has already been used in this chapter so the +hyperlink is switched off using \sty{xkeyval}'s \cs{setkeys} +command. If the chapter number isn't the same, then this entry +hasn't been used in the current chapter. The \texttt{chapter} field +is updated using \ics{glsfieldxdef} (\sectionref{sec:fetchset}) +provided the user hasn't switched off the hyperlink. +(This test is performed using \cs{glsifhyperon}. +\begin{verbatim} +\renewcommand*{\glslinkpostsetkeys}{% + \edef\currentchap{\arabic{chapter}}% + \ifnum\currentchap=\glschapnum{\glslabel}\relax + \setkeys{glslink}{hyper=false}% + \else + \glsifhyperon{\glsfieldxdef{\glslabel}{chapter}{\currentchap}}{}% + \fi +} +\end{verbatim} +Note that this will be confused if you use \cs{gls} etc when the +chapter counter is~0. (That is, before the first \cs{chapter}.) + +See the sample file \samplefile{-chap-hyperfirst} for a complete +document. +\end{example} + +\chapter{Adding an Entry to the Glossary Without Generating Text} +\label{sec:glsadd} + +It is possible to add a line to the glossary file without +generating any text at that point in the document using: +\begin{definition}[\DescribeMacro{\glsadd}] +\cs{glsadd}\oarg{options}\marg{label} +\end{definition} +This is similar to the \glstextlike\ commands, only it doesn't produce +any text (so therefore, there is no \gloskey[glslink]{hyper} key +available in \meta{options} but all the other options that can +be used with \glstextlike\ commands can be passed to \cs{glsadd}). +For example, to add a page range to the glossary number list for the +entry whose label is given by \texttt{set}: +\begin{verbatim} +\glsadd[format=(]{set} +Lots of text about sets spanning many pages. +\glsadd[format=)]{set} +\end{verbatim} + +To add all entries that have been defined, use: +\begin{definition}[\DescribeMacro{\glsaddall}] +\cs{glsaddall}\oarg{options} +\end{definition} +The optional argument is the same as for \cs{glsadd}, except +there is also a key \gloskey[glsaddall]{types} which can be +used to specify which glossaries to use. This should be a +comma separated list. For example, if you only want to add +all the entries belonging to the list of acronyms (specified by +the glossary type \ics{acronymtype}) and a list of +notation (specified by the glossary type \texttt{notation}) then you can +do: +\begin{verbatim} +\glsaddall[types={\acronymtype,notation}] +\end{verbatim} + +\begin{important} +Note that \cs{glsadd} and \cs{glsaddall} add the current location to +the \gls{numberlist}. In the case of \cs{glsaddall}, all entries in the +glossary will have the same location in the number list. If you want +to use \cs{glsaddall}, it's best to suppress the number list with +the \pkgopt{nonumberlist} package option. (See +sections~\ref{sec:pkgopts-printglos} and~\ref{sec:numberlists}.) +\end{important} + +There is now a variation of \cs{glsaddall} that skips any entries +that have already been used: +\begin{definition}[\DescribeMacro\glsaddallunused] +\cs{glsaddallunused}\oarg{list} +\end{definition} +This command uses \cs{glsadd}\texttt{[format=@gobble]} which will +ignore this location in the number list. The optional argument +\meta{list} is a comma-separated list of glossary types. If omitted, +it defaults to the list of all defined glossaries. + +If you want to use \cs{glsaddallunused}, it's best to place the +command at the end of the document to ensure that all the commands +you intend to use have already been used. Otherwise you could end up +with a spurious comma or dash in the location list. + +\begin{example}{Dual Entries}{ex:dual} +The example file \samplefile{-dual} makes use of \cs{glsadd} to +allow for an entry that should appear both in the main glossary and +in the list of acronyms. This example sets up the list of acronyms +using the \pkgopt{acronym} package option: +\begin{verbatim} +\usepackage[acronym]{glossaries} +\end{verbatim} +A new command is then defined to make it easier to define dual +entries: +\begin{verbatim} +\newcommand*{\newdualentry}[5][]{% + \newglossaryentry{main-#2}{name={#4},% + text={#3\glsadd{#2}},% + description={#5},% + #1 + }% + \newacronym{#2}{#3\glsadd{main-#2}}{#4}% +} +\end{verbatim} +This has the following syntax: +\begin{alltt} +\ics{newdualentry}\oarg{options}\marg{label}\marg{abbrv}\marg{long}\marg{description} +\end{alltt} +You can then define a new dual entry: +\begin{verbatim} +\newdualentry{svm}% label + {SVM}% abbreviation + {support vector machine}% long form + {Statistical pattern recognition technique}% description +\end{verbatim} +Now you can reference the acronym with \verb|\gls{svm}| or you can +reference the entry in the main glossary with \verb|\gls{main-svm}|. +\end{example} + +\chapter{Cross-Referencing Entries} +\label{sec:crossref} + +\begin{important} +You must use \ics{makeglossaries} (\optsor23) or +\ics{makenoidxglossaries} (\opt1) \emph{before} defining any +terms that cross-reference entries. If any of the terms that you have +cross-referenced don't appear in the glossary, check that you have +put \cs{makeglossaries}\slash\cs{makenoidxglossaries} before all +entry definitions. The \gls{glossaries-extra} package provides +better cross-reference handling. +\end{important} + +There are several ways of cross-referencing entries in the +glossary: + +\begin{enumerate} +\item You can use commands such as \ics{gls} in the +entries description. For example: +\begin{verbatim} +\newglossaryentry{apple}{name=apple, +description={firm, round fruit. See also \gls{pear}}} +\end{verbatim} +Note that with this method, if you don't use the cross-referenced term +in the main part of the document, you will need two runs of +\gls{makeglossaries}: +\begin{verbatim} +latex filename +makeglossaries filename +latex filename +makeglossaries filename +latex filename +\end{verbatim} + +\item As described in \sectionref{sec:newglosentry}, you can use the +\gloskey{see} key when you define the entry. For example: +\begin{verbatim} +\newglossaryentry{MaclaurinSeries}{name={Maclaurin +series}, +description={Series expansion}, +see={TaylorsTheorem}} +\end{verbatim} +Note that in this case, the entry with the \gloskey{see} key will +automatically be added to the glossary, but the cross-referenced +entry won't. You therefore need to ensure that you use the +cross-referenced term with the commands described in +\sectionref{sec:glslink} or \sectionref{sec:glsadd}. + +The \qt{see} tag is produce using \ics{seename}, but can be +overridden in specific instances using square brackets +at the start of the \gloskey{see} value. For example: +\begin{verbatim} +\newglossaryentry{MaclaurinSeries}{name={Maclaurin +series}, +description={Series expansion}, +see=[see also]{TaylorsTheorem}} +\end{verbatim} +Take care if you want to use the optional argument of commands such +as \ics{newacronym} or \ics{newterm} as the value will need to be +grouped. For example: +\begin{verbatim} +\newterm{seal} +\newterm[see={[see also]seal}]{sea lion} +\end{verbatim} +Similarly if the value contains a list. For example: +\begin{verbatim} +\glossaryentry{lemon}{ + name={lemon}, + description={Yellow citrus fruit} +} +\glossaryentry{lime} +{ + name={lime}, + description={Green citrus fruit} +} +\glossaryentry{citrus} +{ + name={citrus}, + description={Plant in the Rutaceae family}, + see={lemon,lime} +} +\end{verbatim} + +\item After you have defined the entry, use +\begin{definition}[\DescribeMacro{\glssee}] +\cs{glssee}\oarg{tag}\marg{label}\marg{xr label list} +\end{definition} +where \meta{xr label list} is a comma-separated list of entry +labels to be cross-referenced, \meta{label} is the label of the +entry doing the cross-referencing and \meta{tag} is the \qt{see} tag. +(The default value of \meta{tag} is \ics{seename}.) +For example: +\begin{verbatim} +\glssee[see also]{series}{FourierSeries,TaylorsTheorem} +\end{verbatim} +Note that this automatically adds the entry given by \meta{label} to +the glossary but doesn't add the cross-referenced entries (specified +by \meta{xr label list}) to the glossary. +\end{enumerate} + +In both cases~2 and 3 above, the cross-referenced information +appears in the \gls{numberlist}, whereas in case~1, the +cross-referenced information appears in the description. (See the +\samplefile{-crossref} example file that comes with this package.) +This means that in cases~2 and~3, the cross-referencing information +won't appear if you have suppressed the \gls*{numberlist}. In this +case, you will need to activate the \gls*{numberlist} for the given +entries using \gloskey{nonumberlist=false}. Alternatively, if you +just use the \gloskey{see} key instead of \ics{glssee}, you can +automatically activate the \gls*{numberlist} using the +\pkgopt{seeautonumberlist} package option. + +\section{Customising Cross-reference Text} +\label{sec:customxr} + +When you use either the \gloskey{see} key or the command +\cs{glssee}, the cross-referencing information will be typeset in the +glossary according to: +\begin{definition}[\DescribeMacro{\glsseeformat}] +\cs{glsseeformat}\oarg{tag}\marg{label-list}\marg{location} +\end{definition} +The default definition of \cs{glsseeformat} is: +\begin{display} +\cs{emph}\marg{tag} \cs{glsseelist}\marg{label-list} +\end{display} +Note that the location is always ignored.\footnote{\gls{makeindex} +will always assign a location number, even if it's not needed, so it +needs to be discarded.} For example, if you want the tag to appear +in bold, you can do:\footnote{If you redefine \cs{glsseeformat}, +keep the default value of the optional argument as \ics{seename} as +both \gloskey{see} and \cs{glssee} explicitly write +\texttt[\cs{seename}\texttt] in the output file if no optional +argument is given.} +\begin{verbatim} +\renewcommand*{\glsseeformat}[3][\seename]{\textbf{#1} + \glsseelist{#2}} +\end{verbatim} + + +The list of labels is dealt with by \cs{glsseelist}, which iterates +through the list and typesets each entry in the label. The entries +are separated by +\begin{definition}[\DescribeMacro{\glsseesep}] +\cs{glsseesep} +\end{definition} +or (for the last pair) +\begin{definition}[\DescribeMacro{\glsseelastsep}] +\cs{glsseelastsep} +\end{definition} +These default to ``",\space"'' and +\qt{\cs{space}\ics{andname}\cs{space}} respectively. The list entry text +is displayed using: +\begin{definition}[\DescribeMacro{\glsseeitemformat}] +\cs{glsseeitemformat}\marg{label} +\end{definition} +This defaults to \ics{glsentrytext}\marg{label}.\footnote{In +versions before 3.0, \cs{glsentryname} was used, but this could cause +problems when the \gloskey{name} key was \glsd{sanitize}.} For example, to +make the cross-referenced list use small caps: +\begin{verbatim} +\renewcommand{\glsseeitemformat}[1]{% + \textsc{\glsentrytext{#1}}} +\end{verbatim} + +\begin{important} +You can use \ics{glsseeformat} and \ics{glsseelist} in the main body +of the text, but they won't automatically add the cross-referenced +entries to the glossary. If you want them added with that location, +you can do: +\begin{verbatim} +Some information (see also +\glsseelist{FourierSeries,TaylorsTheorem}% +\glsadd{FourierSeries}\glsadd{TaylorsTheorem}). +\end{verbatim} +\end{important} + +\chapter{Using Glossary Terms Without Links} +\label{sec:glsnolink} + +The commands described in this section display entry details without +adding any information to the glossary. They don't use +\ics{glstextformat}, they don't have any optional arguments, they +don't affect the \firstuseflag\ and, apart from \ics{glshyperlink}, +they don't produce hyperlinks. + +\begin{important} +Commands that aren't expandable will be ignored by PDF bookmarks, so +you will need to provide an alternative via \sty{hyperref}'s +\cs{texorpdfstring} if you want to use them in sectioning commands. +(This isn't specific to the \styfmt{glossaries} package.) See the +\sty{hyperref} documentation for further details. All the commands +that convert the first letter to upper case aren't expandable. +The other commands depend on whether their corresponding keys were +assigned non-expandable values. +\end{important} + +If you want to title case a field, you can use: +\begin{definition}[\DescribeMacro\glsentrytitlecase] +\cs{glsentrytitlecase}\marg{label}\marg{field} +\end{definition} +where \meta{label} is the label identifying the glossary entry, +\meta{field} is the field label (see \tableref{tab:fieldmap}). +For example: +\begin{verbatim} +\glsentrytitlecase{sample}{desc} +\end{verbatim} +(If you want title-casing in your glossary style, you might want to +investigate the \sty{glossaries-extra} package.) + +Note that this command has the same limitations as \cs{makefirstuc} which is +used by commands like \cs{Gls} and \cs{Glsentryname} to upper-case +the first letter (see the notes about \cs{Gls} in \sectionref{sec:gls-like}). + +\begin{definition}[\DescribeMacro{\glsentryname}] +\cs{glsentryname}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryname}] +\cs{Glsentryname}\marg{label} +\end{definition} +These commands display the name of the glossary entry given by +\meta{label}, as specified by the \gloskey{name} key. +\cs{Glsentryname} makes the first letter upper case. +Neither of these commands check for the existence of \meta{label}. +The first form \cs{glsentryname} is expandable (unless the name +contains unexpandable commands). Note that this may be different from the values of +the \gloskey{text} or \gloskey{first} keys. In general it's better +to use \cs{glsentrytext} or \cs{glsentryfirst} instead of +\cs{glsentryname}. + +\begin{important} +In general it's best to avoid \cs{Glsentryname} with abbreviations. Instead, +consider using \cs{Glsentrylong}, \cs{Glsentryshort} or \cs{Glsentryfull}. +\end{important} + +\begin{definition}[\DescribeMacro{\glossentryname}] +\cs{glossentryname}\marg{label} +\end{definition} +This is like \cs{glsnamefont}\{\cs{glsentryname\marg{label}}\} +but also checks for the existence of \meta{label}. This command is +not expandable. It's used in the predefined glossary styles, so if +you want to change the way the name is formatted in the glossary, +you can redefine \cs{glsnamefont} to use the required fonts. For +example: +\begin{verbatim} +\renewcommand*{\glsnamefont}[1]{\textmd{\sffamily #1}} +\end{verbatim} +\begin{definition}[\DescribeMacro{\Glossentryname}] +\cs{Glossentryname}\marg{label} +\end{definition} +This is like \cs{glossentryname} but makes the first letter of the +name upper case. + +\begin{definition}[\DescribeMacro{\glsentrytext}] +\cs{glsentrytext}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentrytext}] +\cs{Glsentrytext}\marg{label} +\end{definition} +These commands display the subsequent use text for the glossary +entry given by \meta{label}, as specified by the \gloskey{text} key. +\cs{Glsentrytext} makes the first letter upper case. +The first form is expandable (unless the text contains unexpandable +commands). The second form is not expandable. Neither checks for the +existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\glsentryplural}] +\cs{glsentryplural}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryplural}] +\cs{Glsentryplural}\marg{label} +\end{definition} +These commands display the subsequent use plural text for the +glossary entry given by \meta{label}, as specified by the +\gloskey{plural} key. \cs{Glsentryplural} makes the first letter +upper case. +The first form is expandable (unless the value of that key contains unexpandable +commands). The second form is not expandable. Neither checks for the +existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\glsentryfirst}] +\cs{glsentryfirst}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryfirst}] +\cs{Glsentryfirst}\marg{label} +\end{definition} +These commands display the \firstusetext\ for the glossary entry +given by \meta{label}, as specified by the \gloskey{first} key. +\cs{Glsentryfirst} makes the first letter upper case. +The first form is expandable (unless the value of that key contains unexpandable +commands). The second form is not expandable. Neither checks for the +existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\glsentryfirstplural}] +\cs{glsentryfirstplural}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryfirstplural}] +\cs{Glsentryfirstplural}\marg{label} +\end{definition} +These commands display the plural form of the \firstusetext\ for the +glossary entry given by \meta{label}, as specified by the +\gloskey{firstplural} key. \cs{Glsentryfirstplural} makes the first +letter upper case. +The first form is expandable (unless the value of that key contains unexpandable +commands). The second form is not expandable. Neither checks for the +existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\glsentrydesc}] +\cs{glsentrydesc}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentrydesc}] +\cs{Glsentrydesc}\marg{label} +\end{definition} +These commands display the description for the glossary entry given +by \meta{label}. \cs{Glsentrydesc} makes the first letter upper case. +The first form is expandable (unless the value of that key contains unexpandable +commands). The second form is not expandable. Neither checks for the +existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\glossentrydesc}] +\cs{glossentrydesc}\marg{label} +\end{definition} +This is like \cs{glsentrydesc}\marg{label} +but also checks for the existence of \meta{label}. This command is +not expandable. It's used in the predefined glossary styles to +display the description. +\begin{definition}[\DescribeMacro{\Glossentrydesc}] +\cs{Glossentrydesc}\marg{label} +\end{definition} +This is like \cs{glossentrydesc} but converts the first letter to +upper case. This command is not expandable. + +\begin{definition}[\DescribeMacro{\glsentrydescplural}] +\cs{glsentrydescplural}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentrydescplural}] +\cs{Glsentrydescplural}\marg{label} +\end{definition} +These commands display the plural description for the glossary entry +given by \meta{label}. \cs{Glsentrydescplural} makes the first +letter upper case. +The first form is expandable (unless the value of that key contains unexpandable +commands). The second form is not expandable. Neither checks for the +existence of \meta{label}. + + +\begin{definition}[\DescribeMacro{\glsentrysymbol}] +\cs{glsentrysymbol}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentrysymbol}] +\cs{Glsentrysymbol}\marg{label} +\end{definition} +These commands display the symbol for the glossary entry given by +\meta{label}. \cs{Glsentrysymbol} makes the first letter upper case. +The first form is expandable (unless the value of that key contains unexpandable +commands). The second form is not expandable. Neither checks for the +existence of \meta{label}. + + +\begin{definition}[\DescribeMacro\glsletentryfield] +\cs{glsletentryfield}\marg{cs}\marg{label}\marg{field} +\end{definition} +This command doesn't display anything. It merely fetches the +value associated with the given field (where the available field names +are listed in \tableref{tab:fieldmap}) and stores the result +in the control sequence \meta{cs}. For example, to store +the description for the entry whose label is \qt{apple} in the +control sequence \verb|\tmp|: +\begin{verbatim} +\glsletentryfield{\tmp}{apple}{desc} +\end{verbatim} + +\begin{definition}[\DescribeMacro{\glossentrysymbol}] +\cs{glossentrysymbol}\marg{label} +\end{definition} +This is like \cs{glsentrysymbol}\marg{label} +but also checks for the existence of \meta{label}. This command is +not expandable. It's used in some of the predefined glossary styles to +display the symbol. +\begin{definition}[\DescribeMacro{\Glossentrysymbol}] +\cs{Glossentrysymbol}\marg{label} +\end{definition} +This is like \cs{glossentrysymbol} but converts the first letter to +upper case. This command is not expandable. + +\begin{definition}[\DescribeMacro{\glsentrysymbolplural}] +\cs{glsentrysymbolplural}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentrysymbolplural}] +\cs{Glsentrysymbolplural}\marg{label} +\end{definition} +These commands display the plural symbol for the glossary entry +given by \meta{label}. \cs{Glsentrysymbolplural} makes the first +letter upper case. +The first form is expandable (unless the value of that key contains unexpandable +commands). The second form is not expandable. Neither checks for the +existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\glsentryuseri}] +\cs{glsentryuseri}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryuseri}] +\cs{Glsentryuseri}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glsentryuserii}] +\cs{glsentryuserii}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryuserii}] +\cs{Glsentryuserii}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glsentryuseriii}] +\cs{glsentryuseriii}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryuseriii}] +\cs{Glsentryuseriii}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glsentryuseriv}] +\cs{glsentryuseriv}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryuseriv}] +\cs{Glsentryuseriv}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glsentryuserv}] +\cs{glsentryuserv}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryuserv}] +\cs{Glsentryuserv}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glsentryuservi}] +\cs{glsentryuservi}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryuservi}] +\cs{Glsentryuservi}\marg{label} +\end{definition} +These commands display the value of the user keys for the glossary +entry given by \meta{label}. +The lower case forms are expandable (unless the value of the key +contains unexpandable commands). The commands beginning with an +upper case letter convert the first letter of the required value to +upper case and are not expandable. None of these commands check for +the existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\glshyperlink}] +\cs{glshyperlink}\oarg{link text}\marg{label} +\end{definition} +This command provides a hyperlink to the glossary entry given by +\meta{label} \textbf{but does not add any information to the +glossary file}. The link text is given by +\ics{glsentrytext}\marg{label} by default\footnote{versions before +3.0 used \ics{glsentryname} as the default, but this could cause +problems when \gloskey{name} had been \glsd{sanitize}.}, but can be +overridden using the optional argument. Note that the hyperlink will +be suppressed if you have used \ics{glsdisablehyper} or if you +haven't loaded the \sty{hyperref} package. + +\begin{important} +If you use \cs{glshyperlink}, you need to ensure that the relevant +entry has been added to the glossary using any of the commands +described in \sectionref{sec:glslink} or \sectionref{sec:glsadd} +otherwise you will end up with an undefined link. +\end{important} + +The next two commands are only available with \opt1 or with the +\pkgopt{savenumberlist} package option: +\begin{definition}[\DescribeMacro{\glsentrynumberlist}] +\cs{glsentrynumberlist}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glsdisplaynumberlist}] +\cs{glsdisplaynumberlist}\marg{label} +\end{definition} +Both display the \gls{numberlist} for the entry given by +\meta{label}. When used with \opt1 a~rerun is required to ensure +this list is up-to-date, when used with \optsor23 +a run of \gls{makeglossaries} (or \gls{makeindex}\slash\gls{xindy}) +followed by one or two runs of \LaTeX\ is required. + +The first command, \cs{glsentrynumberlist}, simply displays +the number list as is. The second command, +\cs{glsdisplaynumberlist}, formats the list using: +\begin{definition}[\DescribeMacro{\glsnumlistsep}] +\cs{glsnumlistsep} +\end{definition} +as the separator between all but the last two elements and +\begin{definition}[\DescribeMacro{\glsnumlistlastsep}] +\cs{glsnumlistlastsep} +\end{definition} +between the final two elements. The defaults are +\verb*|, | and \verb*| \& |, respectively. + +\begin{important} +\cs{glsdisplaynumberlist} is fairly experimental. It works with +\opt1, but for \optsor23 it only works when the default counter +format is used (that is, when the \gloskey[glslink]{format} key is +set to \texttt{glsnumberformat}). This command will only work with +\sty{hyperref} if you choose \opt1. If you try using this command +with \optsor23 and \sty{hyperref}, \cs{glsentrynumberlist} will be +used instead. +\end{important} + +For further information see \ifpdf section~\ref*{sec:code:glsnolink} +\fi \qt{Displaying entry details without adding information to the +glossary} in the documented code (\texttt{glossaries-code.pdf}). + +\chapter{Displaying a glossary} +\label{sec:printglossary} + +All defined glossaries may be displayed using: +\begin{description} +\itempar{\opt1:} +\begin{definition}[\DescribeMacro{\printnoidxglossaries}] +\cs{printnoidxglossaries} +\end{definition} +(Must be used with \ics{makenoidxglossaries} in the preamble.) + +\itempar{\optsand23:} +\begin{definition}[\DescribeMacro{\printglossaries}] +\cs{printglossaries} +\end{definition} +(Must be used with \ics{makeglossaries} in the preamble.) +\end{description} + +These commands will display all the glossaries in the order in which +they were defined. Note that, in the case of \optsand23, no +glossaries will appear until you have either used the Perl script +\gls{makeglossaries} or Lua script \gls{makeglossaries-lite.lua} or +have directly used \gls{makeindex} or \gls{xindy} (as described in +\sectionref{sec:makeglossaries}). (While the external files are +missing, these commands will just do \cs{null} for each missing +glossary to assist dictionary style documents that just use +\cs{glsaddall} without inserting any text. If you use +\gls{glossaries-extra}, it will insert a heading and boilerplate text when the +external files are missing. The extension package also provides +\cs{printunsrtglossaries} as an alternative. See the +\gls{glossaries-extra} manual for further details.) + +If the glossary still does not appear after you re-\LaTeX\ your +document, check the \gls*{makeindex}\slash\gls*{xindy} log files to +see if there is a problem. With \opt1, you just need two \LaTeX\ +runs to make the glossaries appear, but you may need further runs to +make the \glspl{numberlist} up-to-date. + +An individual glossary can be displayed using: +\begin{description} +\itempar{\opt1:} +\begin{definition}[\DescribeMacro{\printnoidxglossary}] +\cs{printnoidxglossary}\oarg{options} +\end{definition} +(Must be used with \ics{makenoidxglossaries} in the preamble.) + +\itempar{\optsand23:} +\begin{definition}[\DescribeMacro{\printglossary}] +\cs{printglossary}\oarg{options} +\end{definition} +(Must be used with \ics{makeglossaries} in the preamble.) +\end{description} +where \meta{options} is a \meta{key}=\meta{value} list of options. +(Again, when the associated external file is missing, \cs{null} is +inserted into the document.) + +The following keys are available: +\begin{description} +\item[{\gloskey[printglossary]{type}}] The value of this key +specifies which glossary to print. If omitted, the default +glossary is assumed. For example, to print the list of acronyms: +\begin{verbatim} +\printglossary[type=\acronymtype] +\end{verbatim} +Note that you can't display an ignored glossary, so don't try +setting \gloskey[printglossary]{type} to the name of a glossary that +was defined using \ics{newignoredglossary}, described in +\sectionref{sec:newglossary}. (You can display an ignored glossary +with \cs{printunsrtglossary} provided by \gls{glossaries-extra}.) + +\item[{\gloskey[printglossary]{title}}] This is the glossary's +title (overriding the title specified when the glossary was +defined). + +\item[{\gloskey[printglossary]{toctitle}}] This is the title +to use for the table of contents (if the \pkgopt{toc} package +option has been used). It may also be used for the page header, +depending on the page style. If omitted, the value of +\gloskey[printglossary]{title} is used. + +\item[{\gloskey[printglossary]{style}}] This specifies which +glossary style to use for this glossary, overriding the effect +of the \pkgopt{style} package option or \ics{glossarystyle}. + +\item[{\gloskey[printglossary]{numberedsection}}] This specifies +whether to use a numbered section for this glossary, overriding +the effect of the \pkgopt{numberedsection} package option. This +key has the same syntax as the \pkgopt{numberedsection} package +option, described in \sectionref{sec:pkgopts-sec}. + +\item[{\gloskey[printglossary]{nonumberlist}}] This is a boolean +key. If true (\verb|nonumberlist=true|) the numberlist is suppressed +for this glossary. If false (\verb|nonumberlist=false|) the +numberlist is displayed for this glossary. + +\item[{\gloskey[printglossary]{nogroupskip}}] This is a boolean +key. If true the vertical gap between groups +is suppressed for this glossary. + +\item[{\gloskey[printglossary]{nopostdot}}] This is a boolean +key. If true the full stop after the description +is suppressed for this glossary. + +\item[{\gloskey[printglossary]{entrycounter}}] This is a boolean +key. Behaves similar to the package option of the same name. +The corresponding package option must be used to make \ics{glsrefentry} +work correctly. + +\item[{\gloskey[printglossary]{subentrycounter}}] This is a boolean +key. Behaves similar to the package option of the same name. If you +want to set both \gloskey{entrycounter} and +\gloskey{subentrycounter}, make sure you specify +\gloskey{entrycounter} first. The corresponding package option must +be used to make \ics{glsrefentry} work correctly. + +\item[{\gloskey[printnoidxglossary]{sort}}] This key is only +available for \opt1. Possible values are: \texttt{word} (word +order), \texttt{letter} (letter order), \texttt{standard} (word or +letter ordering taken from the \pkgopt{order} package option), +\texttt{use} (order of use), \texttt{def} (order of definition) +\texttt{nocase} (case-insensitive) or \texttt{case} (case-sensitive). +Note that the word and letter comparisons (that is, everything other +than \texttt{sort=use} and \texttt{sort=def}) just use a simple +character code comparison. For a locale-sensitive sort, you must use +either \gls{xindy} (\opt3) or \gls{bib2gls} (\opt4). Note that \gls{bib2gls} +provides many other sort options. + +\begin{important} +If you use the \texttt{use} or \texttt{def} values make sure +that you select a glossary style that doesn't have a visual +indicator between groups, as the grouping no longer makes sense. +Consider using the \pkgopt{nogroupskip} option. +\end{important} + +{\raggedright +The word and letter order sort methods use +\sty{datatool}'s +\ics{dtlwordindexcompare} and \ics{dtlletterindexcompare} handlers. +The case-insensitive sort method uses \sty{datatool}'s +\ics{dtlicompare} handler. The case-sensitive sort method uses +\sty{datatool}'s \ics{dtlcompare} handler. See the \sty{datatool} +documentation for further details. +\par} + +If you don't get an error with \texttt{sort=use} and +\texttt{sort=def} but you do get an error with one of the other sort +options, then you probably need to use the +\pkgopt[true]{sanitizesort} package option or make sure none of the +entries have fragile commands in their \gloskey{sort} field. +\end{description} + +By default, the glossary is started either by \ics{chapter*} or by +\ics{section*}, depending on whether or not \ics{chapter} is defined. +This can be overridden by the \pkgopt{section} package option or the +\ics{setglossarysection} command. Numbered sectional units can be +obtained using the \pkgopt{numberedsection} package option. Each +glossary sets the page header via the command +\begin{definition}[\DescribeMacro\glsglossarymark] +\ics{glsglossarymark}\marg{title} +\end{definition} +If this mechanism is unsuitable for your chosen class file or page +style package, you will need to redefine \ics{glsglossarymark}. Further +information about these options and commands is given in +\sectionref{sec:pkgopts-sec}. + +Information can be added to the start of the glossary (after the +title and before the main body of the glossary) by redefining +\begin{definition}[\DescribeMacro{\glossarypreamble}] +\cs{glossarypreamble} +\end{definition} +For example: +\begin{verbatim} +\renewcommand{\glossarypreamble}{Numbers in italic +indicate primary definitions.} +\end{verbatim} +This needs to be done before the glossary is displayed. + +If you want a different preamble per glossary you can use +\begin{definition}[\DescribeMacro{\setglossarypreamble}] +\cs{setglossarypreamble}\oarg{type}\marg{preamble text} +\end{definition} +If \meta{type} is omitted, \cs{glsdefaulttype} is used. + +For example: +\begin{verbatim} +\setglossarypreamble{Numbers in italic +indicate primary definitions.} +\end{verbatim} +This will print the given preamble text for the main glossary, +but not have any preamble text for any other glossaries. + +There is an analogous command to \cs{glossarypreamble} called +\begin{definition}[\DescribeMacro{\glossarypostamble}] +\cs{glossarypostamble} +\end{definition} +which is placed at the end of each glossary. + +\begin{example}{Switch to Two Column Mode for Glossary}{ex:twocolumn} +Suppose you are using the \glostyle{superheaderborder} +style\footnote{you can't use the \glostyle{longheaderborder} style +for this example as you can't use the \env{longtable} environment in +two column mode.}, and you want the glossary to be in two columns, +but after the glossary you want to switch back to one column mode, +you could do: +\begin{verbatim} +\renewcommand*{\glossarysection}[2][]{% + \twocolumn[{\chapter*{#2}}]% + \setlength\glsdescwidth{0.6\linewidth}% + \glsglossarymark{\glossarytoctitle}% +} + +\renewcommand*{\glossarypostamble}{\onecolumn} +\end{verbatim} + +\end{example} + +Within each glossary, each entry name is formatted according to +\begin{definition}[\DescribeMacro{\glsnamefont}] +\cs{glsnamefont}\marg{name} +\end{definition} +which takes one argument: the entry name. This command is always +used regardless of the glossary style. By default, \cs{glsnamefont} +simply displays its argument in whatever the surrounding font +happens to be. This means that in the list-like glossary styles +(defined in the \sty{glossary-list} style file) the name will appear +in bold, since the name is placed in the optional argument of +\cs{item}, whereas in the tabular styles (defined in the +\sty{glossary-long} and \sty{glossary-super} style files) the name +will appear in the normal font. The hierarchical glossary styles +(defined in the \sty{glossary-tree} style file) also set the name in +bold. + +If you want to change the font for the description, or if you +only want to change the name font for some types of entries +but not others, you might want to consider using the +\sty{glossaries-extra} package. + +\begin{example}{Changing the Font Used to Display Entry Names in the +Glossary}{ex:glsnamefont} +Suppose you want all the entry names to appear in +medium weight small caps in your glossaries, then you can do: +\begin{verbatim} +\renewcommand{\glsnamefont}[1]{\textsc{\mdseries #1}} +\end{verbatim} +\end{example} + +\chapter[Xindy (Option 3)]{Xindy (\ifpdf\opt3\else Option 3\fi)} +\label{sec:xindy} + +If you want to use \gls{xindy} to sort the glossary, you +must use the package option \pkgopt{xindy}: +\begin{verbatim} +\usepackage[xindy]{glossaries} +\end{verbatim} +This ensures that the glossary information is written in +\gls*{xindy} syntax. + +\sectionref{sec:makeglossaries} covers how to use the external +\gls{indexingapp}, and \sectionref{sec:locationsyntax} covers the +issues involved in the location syntax. This section covers the +commands provided by the \styfmt{glossaries} package that allow you +to adjust the \gls{xindy} style file (\filetype{.xdy}) and +parameters. + +To assist writing information to the \gls{xindy} style +file, the \styfmt{glossaries} package provides the following +commands: +\begin{definition}[\DescribeMacro{\glsopenbrace}] +\cs{glsopenbrace} +\end{definition} +\begin{definition}[\DescribeMacro{\glsclosebrace}] +\cs{glsclosebrace} +\end{definition} +which produce an open and closing brace. (This is needed because +\verb|\{| and \verb|\}| don't expand to a simple brace character +when written to a file.) Similarly, you can write a percent +character using: +\begin{definition}[\DescribeMacro{\glspercentchar}] +\cs{glspercentchar} +\end{definition} +and a tilde character using: +\begin{definition}[\DescribeMacro{\glstildechar}] +\cs{glstildechar} +\end{definition} +For example, a newline character is specified in a \gls{xindy} style +file using \verb|~n| so you can use \texttt{\cs{glstildechar} n} +to write this correctly (or you can do \verb|\string~n|). +A backslash can be written to a file using +\begin{definition}[\DescribeMacro{\glsbackslash}] +\cs{glsbackslash} +\end{definition} + +In addition, if you are using a package that makes the double +quote character active (e.g. \sty{ngerman}) you can use: +\begin{definition}[\DescribeMacro{\glsquote}] +\cs{glsquote}\marg{text} +\end{definition} +which will produce \verb|"|\meta{text}\verb|"|. Alternatively, +you can use \verb|\string"| to write the double-quote character. +This document assumes that the double quote character has not been +made active, so the examples just use \verb|"| for clarity. + +If you want greater control over the \gls{xindy} style file than is +available through the \LaTeX\ commands provided by the +\styfmt{glossaries} package, you will need to edit the \gls*{xindy} +style file. In which case, you must use \ics{noist} to prevent the +style file from being overwritten by the \styfmt{glossaries} +package. For additional information about \gls*{xindy}, read the +\gls*{xindy} documentation. I'm sorry I can't provide any assistance +with writing \gls*{xindy} style files. If you need help, I recommend +you ask on the \gls*{xindy} mailing list +(\url{http://xindy.sourceforge.net/mailing-list.html}). + +\section{Language and Encodings} +\label{sec:langenc} + +When you use \gls{xindy}, you need to specify the language +and encoding used (unless you have written your own custom +\gls*{xindy} style file that defines the relevant alphabet +and sort rules). If you use \gls{makeglossaries}, +this information is obtained from the document's auxiliary +(\filetype{.aux}) file. The \gls{makeglossaries} script attempts to +find the root language given your document settings, but in the +event that it gets it wrong or if \gls*{xindy} doesn't support +that language, then you can specify the required language using: +\begin{definition}[\DescribeMacro{\GlsSetXdyLanguage}] +\cs{GlsSetXdyLanguage}\oarg{glossary type}\marg{language} +\end{definition} +where \meta{language} is the name of the language. The +optional argument can be used if you have multiple glossaries +in different languages. If \meta{glossary type} is omitted, it +will be applied to all glossaries, otherwise the language +setting will only be applied to the glossary given by +\meta{glossary type}. + +If the \sty{inputenc} package is used, the encoding will be +obtained from the value of \ics{inputencodingname}. +Alternatively, you can specify the encoding using: +\begin{definition}[\DescribeMacro{\GlsSetXdyCodePage}] +\cs{GlsSetXdyCodePage}\marg{code} +\end{definition} +where \meta{code} is the name of the encoding. For example: +\begin{verbatim} +\GlsSetXdyCodePage{utf8} +\end{verbatim} + +Note that you can also specify the language and encoding using +the package option +\verb|xindy={language=|\meta{lang}\verb|,codepage=|\meta{code}\verb|}|. +For example: +\begin{verbatim} +\usepackage[xindy={language=english,codepage=utf8}]{glossaries} +\end{verbatim} + +If you write your own custom \gls{xindy} style file that +includes the language settings, you need to set the language +to nothing: +\begin{verbatim} +\GlsSetXdyLanguage{} +\end{verbatim} +(and remember to use \ics{noist} to prevent the style file from +being overwritten). + +\begin{important} +The commands \cs{GlsSetXdyLanguage} and \cs{GlsSetXdyCodePage} +have no effect if you don't use \gls{makeglossaries}. If +you call \gls{xindy} without \gls*{makeglossaries} you +need to remember to set the language and encoding using the +\xdyopt{L} and \xdyopt{C} switches. +\end{important} + +\section{Locations and Number lists} +\label{sec:xindyloc} + +If you use \pkgopt{xindy}, the \styfmt{glossaries} package needs to +know which counters you will be using in the \gls{numberlist} in order to correctly format the \gls{xindy} style +file. Counters specified using the \pkgopt{counter} package option +or the \meta{counter} option of \ics{newglossary} are +automatically taken care of, but if you plan to use a different +counter in the \gloskey[glslink]{counter} key for commands like +\ics{glslink}, then you need to identify these counters \emph{before} +\ics{makeglossaries} using: +\begin{definition}[\DescribeMacro{\GlsAddXdyCounters}] +\cs{GlsAddXdyCounters}\marg{counter list} +\end{definition} +where \meta{counter list} is a comma-separated list of counter names. + +The most likely attributes used in the \gloskey[glslink]{format} +key (\locfmt{textrm}, \locfmt{hyperrm} etc) are automatically added +to the \gls{xindy} style file, but if you want to use another +attribute, you need to add it using: +\begin{definition}[\DescribeMacro{\GlsAddXdyAttribute}] +\cs{GlsAddXdyAttribute}\marg{name} +\end{definition} +where \meta{name} is the name of the attribute, as used in +the \gloskey[glslink]{format} key. + +Take care if you have multiple instances of the same location with +different formats. The duplicate locations will be discarded +according to the order in which the attributes are listed. Consider +defining semantic commands to use for primary references. For +example: +\begin{verbatim} +\newcommand*{\primary}[1]{\textbf{#1}} +\GlsAddXdyAttribute{primary} +\end{verbatim} +Then in the document: +\begin{verbatim} +A \gls[format=primary]{duck} is an aquatic bird. +There are lots of different types of \gls{duck}. +\end{verbatim} +This will give the \verb|format=primary| instance preference over +the next use that doesn't use the \gloskey[glslink]{format} key. + +\begin{example}{Custom Font for Displaying a Location}{ex:hyperbfit} +Suppose I want a bold, italic, hyperlinked location. I first need to define a +command that will do this: +\begin{verbatim} +\newcommand*{\hyperbfit}[1]{\textit{\hyperbf{#1}}} +\end{verbatim} +but with \gls{xindy}, I also need to add this as an allowed +attribute: +\begin{verbatim} +\GlsAddXdyAttribute{hyperbfit} +\end{verbatim} +Now I can use it in the optional argument of commands like +\ics{gls}: +\begin{verbatim} +Here is a \gls[format=hyperbfit]{sample} entry. +\end{verbatim} +(where \texttt{sample} is the label of the required entry). +\end{example} + +\begin{important} +Note that \cs{GlsAddXdyAttribute} has no effect if \ics{noist} is +used or if \ics{makeglossaries} is omitted. +\cs{GlsAddXdyAttribute} must be used before \ics{makeglossaries}. +Additionally, \cs{GlsAddXdyCounters} must come before +\cs{GlsAddXdyAttribute}. +\end{important} + +If the location numbers include formatting commands, then +you need to add a location style in the appropriate format using +\begin{definition}[\DescribeMacro{\GlsAddXdyLocation}] +\cs{GlsAddXdyLocation}\oarg{prefix-location}\marg{name}\marg{definition} +\end{definition} +where \meta{name} is the name of the format and \meta{definition} is +the \gls{xindy} definition. The optional argument \meta{prefix-location} +is needed if \cs{theH}\meta{counter} either isn't defined or is +different from \cs{the}\meta{counter}. +Be sure to also read \sectionref{sec:locationsyntax} for some issues +that you may encounter. + +\begin{important} +Note that \cs{GlsAddXdyLocation} has no effect if \ics{noist} is +used or if \ics{makeglossaries} is omitted. +\cs{GlsAddXdyLocation} must be used before \ics{makeglossaries}. +\end{important} + +\begin{example}{Custom Numbering System for Locations}{ex:customloc} +Suppose I decide to use a somewhat eccentric numbering +system for sections where I redefine \cs{thesection} as follows: +\begin{verbatim} +\renewcommand*{\thesection}{[\thechapter]\arabic{section}} +\end{verbatim} +If I haven't done "counter=section" in the package +option, I need to specify that the counter will be used as a +location number: +\begin{verbatim} +\GlsAddXdyCounters{section} +\end{verbatim} +Next I need to add the location style (\cs{thechapter} is assumed to +be the standard \verb"\arabic{chapter}"): +\begin{verbatim} +\GlsAddXdyLocation{section}{:sep "[" "arabic-numbers" :sep "]" + "arabic-numbers" +} +\end{verbatim} +Note that if I have further decided to use the \sty{hyperref} +package and want to redefine \cs{theHsection} as: +\begin{verbatim} +\renewcommand*{\theHsection}{\thepart.\thesection} +\renewcommand*{\thepart}{\Roman{part}} +\end{verbatim} +then I need to modify the \cs{GlsAddXdyLocation} code above to: +\begin{verbatim} +\GlsAddXdyLocation["roman-numbers-uppercase"]{section}{:sep "[" + "arabic-numbers" :sep "]" "arabic-numbers" +} +\end{verbatim} +Since \ics{Roman} will result in an empty string if the counter is +zero, it's a good idea to add an extra location to catch this: +\begin{verbatim} +\GlsAddXdyLocation{zero.section}{:sep "[" + "arabic-numbers" :sep "]" "arabic-numbers" +} +\end{verbatim} +This example is illustrated in the sample file +\samplefile{xdy2}. +\end{example} + +\begin{example}{Locations as Dice}{ex:dice} +Suppose I want a rather eccentric page numbering system that's +represented by the number of dots on dice. The \sty{stix} package +provides \cs{dicei}, \ldots, \cs{dicevi} that represent the six +sides of a die. I can define a command that takes a number as its +argument. If the number is less than seven, the appropriate +\cs{dice}\meta{n} command is used otherwise it does \cs{dicevi} the +required number of times with the leftover in a final +\cs{dice}\meta{n}. For example, the number 16 is represented by +\verb|\dicevi\dicevi\diceiv| ($6+6+4=16$). I've called this command +\cs{tallynum} to match the example given earlier in +\sectionref{sec:locationsyntax}: +\begin{verbatim} +\newrobustcmd{\tallynum}[1]{% + \ifnum\number#1<7 + $\csname dice\romannumeral#1\endcsname$% + \else + $\dicevi$% + \expandafter\tallynum\expandafter{\numexpr#1-6}% + \fi +} +\end{verbatim} +Here's the counter command: +\begin{verbatim} +newcommand{\tally}[1]{\tallynum{\arabic{#1}}} +\end{verbatim} +The \ctr{page} counter representation (\cs{thepage}) needs to be +changed to use this command: +\begin{verbatim} +\renewcommand*{\thepage}{\tally{page}} +\end{verbatim} +The \cs{tally} command expands to \cs{tallynum} \marg{number} so +this needs a location class that matches this format: +\begin{verbatim} +\GlsAddXdyLocation{tally}{% + :sep "\string\tallynum\space\glsopenbrace" + "arabic-numbers" + :sep "\glsclosebrace" +} +\end{verbatim} +The space between \cs{tallynum} and \marg{number} is +significant to \gls{xindy} so \cs{space} is required. + +Note that \cs{GlsAddXdyLocation}\marg{name}\marg{definition} will define +commands in the form: +\begin{definition} +\cs{glsX}\meta{counter}"X"\meta{name}\marg{Hprefix}\marg{location} +\end{definition} +for each counter that has been identified either by the +\pkgopt{counter} package option, the \meta{counter} option for +\ics{newglossary} or in the argument of \ics{GlsAddXdyCounters}. +The first argument \meta{Hprefix} is only relevant when used with +the \sty{hyperref} package and indicates that \cs{theH}\meta{counter} +is given by \cs{Hprefix}"."\cs{the}\meta{counter}. + +The sample file \samplefile{xdy}, which comes with the \styfmt{glossaries} +package, uses the default \ctr{page} counter for locations, and it +uses the default \ics{glsnumberformat} and a custom \cs{hyperbfit} +format. A new \gls{xindy} location called \texttt{tallynum}, as +illustrated above, is defined to make the page numbers appear as +dice. In order for the location numbers to +hyperlink to the relevant pages, I~need to redefine the necessary +\cs{glsX}\meta{counter}"X"\meta{format} commands: +\begin{verbatim} +\renewcommand{\glsXpageXglsnumberformat}[2]{% + \linkpagenumber#2% +} + +\renewcommand{\glsXpageXhyperbfit}[2]{% + \textbf{\em\linkpagenumber#2}% +} + +\newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}} +\end{verbatim} +Note that the second argument of \cs{glsXpageXglsnumberformat} is +in the format \cs{tallynum}\marg{n} so the line +\begin{verbatim} + \linkpagenumber#2% +\end{verbatim} +does +\begin{alltt} + \cs{linkpagenumber}\cs{tallynum}\marg{number} +\end{alltt} +so \cs{tallynum} is the first argument of \cs{linkpagenumber} +and \meta{number} is the second argument. +\end{example} + +\begin{important} +This method is very sensitive to the internal definition of the +location command. +\end{important} + +\begin{example}{Locations as Words not Digits}{ex:fmtcount} +Suppose I want the page numbers written as words +rather than digits and I~use the \sty{fmtcount} package to +do this. I~can redefine \ics{thepage} as follows: +\begin{verbatim} +\renewcommand*{\thepage}{\Numberstring{page}} +\end{verbatim} +This \emph{used} to get expanded to \verb|\protect \Numberstringnum |\marg{n} +where \meta{n} is the Arabic page number. This means that I~needed to +define a new location with the form: +\begin{verbatim} +\GlsAddXdyLocation{Numberstring}{:sep "\string\protect\space + \string\Numberstringnum\space\glsopenbrace" + "arabic-numbers" :sep "\glsclosebrace"} +\end{verbatim} +and if I'd used the \cs{linkpagenumber} command from the previous +example, it would need \emph{three} arguments (the first being +\cs{protect}): +\begin{verbatim} +\newcommand{\linkpagenumber}[3]{\hyperlink{page.#3}{#1#2{#3}}} +\end{verbatim} + +The internal definition of \cs{Numberstring} has since changed +so that it now expands to \verb|\Numberstringnum |\marg{n} +(no \cs{protect}). This means that the location class definition +must be changed to: +\begin{verbatim} +\GlsAddXdyLocation{Numberstring}{% no \protect now! + :sep "\string\Numberstringnum\space\glsopenbrace" + "arabic-numbers" :sep "\glsclosebrace"} +\end{verbatim} +and \cs{linkpagenumber} goes back to only two arguments: +\begin{verbatim} +\newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}} +\end{verbatim} +The other change is that \cs{Numberstring} uses +\begin{alltt} +\cs{the}\cs{value}\marg{counter} +\end{alltt} +instead of +\begin{alltt} +\cs{expandafter}\cs{the}\cs{csname} c@\meta{counter}\cs{endcsname} +\end{alltt} +so it hides \cs{c@page} from the location escaping mechanism +(see \sectionref{sec:locationsyntax}). This means that the page +number may be incorrect if the indexing occurs during the output +routine. + +A more recent change to \sty{fmtcount} (v3.03) now puts three +instances of \cs{expandafter} before \verb|\the\value| which +no longer hides \cs{c@page} from the location escaping mechanism, so +the page numbers should once more be correct. Further changes +to the \sty{fmtcount} package may cause a problem again. + +\begin{important} +When dealing with custom formats where the internal definitions +are outside of your control and liable to change, it's best +to provide a wrapper command. +\end{important} + +Instead of directly using \cs{Numberstring} in the definition of +\cs{thepage}, I can provide a custom command in the same form +as the earlier \cs{tally} command: +\begin{verbatim} +\newcommand{\customfmt}[1]{\customfmtnum{\arabic{#1}}} +\newrobustcmd{\customfmtnum}[1]{\Numberstringnum{#1}} +\end{verbatim} +This ensures that the location will always be written to +the indexing file in the form: +\begin{alltt} +:locref "\glsopenbrace\glsclosebrace\glsopenbrace\string\\customfmtnum \marg{n}\glsclosebrace" +\end{alltt} +So the location class can be defined as: +\begin{verbatim} +\GlsAddXdyLocation{customfmt}{ + :sep "\string\customfmtnum\space\glsopenbrace" + "arabic-numbers" + :sep "\glsclosebrace"} +\end{verbatim} + +The sample file +\samplefile{xdy3} illustrates this. +\end{example} + +In the \gls{numberlist}, the locations are sorted according to the list +of provided location classes. The default ordering is: +\texttt{roman-page-numbers} (i, ii, \ldots), \texttt{arabic-page-numbers} +(1, 2, \ldots), \texttt{arabic-section-numbers} (for example, 1.1 if the +compositor is a full stop or 1-1 if the compositor is a +hyphen\footnote{see \ics{glsSetCompositor} described in +\sectionref{sec:setup}}), \texttt{alpha-page-numbers} (a, b, \ldots), +\texttt{Roman-page-numbers} (I, II, \ldots), \texttt{Alpha-page-numbers} +(A, B, \ldots), \texttt{Appendix-page-numbers} (for example, A.1 if the Alpha +compositor is a full stop or A-1 if the Alpha compositor is a +hyphen\footnote{see \ics{glsSetAlphaCompositor} described in +\sectionref{sec:setup}}), user defined location names (as specified +by \ics{GlsAddXdyLocation} in the order in which they were defined), +and finally \texttt{see} (cross-referenced entries).\footnote{With +\gls{glossaries-extra} \texttt{seealso} is appended to the end of +the list.} This ordering can be changed using: + +\begin{definition}[\DescribeMacro\GlsSetXdyLocationClassOrder] +\cs{GlsSetXdyLocationClassOrder}\marg{location names} +\end{definition} +where each location name is delimited by double quote marks and +separated by white space. For example: +\begin{verbatim} +\GlsSetXdyLocationClassOrder{ + "arabic-page-numbers" + "arabic-section-numbers" + "roman-page-numbers" + "Roman-page-numbers" + "alpha-page-numbers" + "Alpha-page-numbers" + "Appendix-page-numbers" + "see" +} +\end{verbatim} +(Remember to add \verb|"seealso"| if you're using +\gls{glossaries-extra}.) + +\begin{important} +Note that \cs{GlsSetXdyLocationClassOrder} has no effect if +\ics{noist} is used or if \ics{makeglossaries} is omitted. +\cs{GlsSetXdyLocationClassOrder} must be used before +\ics{makeglossaries}. +\end{important} + +If a \gls{numberlist} consists of a sequence of consecutive +numbers, the range will be concatenated. The +number of consecutive locations that causes a range formation +defaults to 2, but can be changed using: + +\begin{definition}[\DescribeMacro\GlsSetXdyMinRangeLength] +\cs{GlsSetXdyMinRangeLength}\marg{n} +\end{definition} +For example: +\begin{verbatim} +\GlsSetXdyMinRangeLength{3} +\end{verbatim} +The argument may also be the keyword \texttt{none}, to indicate that +there should be no range formations. See the \gls{xindy} +manual for further details on range formations. + +\begin{important} +Note that \cs{GlsSetXdyMinRangeLength} has no effect if \ics{noist} +is used or if \ics{makeglossaries} is omitted. +\cs{GlsSetXdyMinRangeLength} must be used before +\ics{makeglossaries}. +\end{important} +See also \sectionref{sec:ranges}. + +\section{Glossary Groups} +\label{sec:groups} + +The glossary is divided into groups according to the first +letter of the sort key. The \styfmt{glossaries} package also adds +a number group by default, unless you suppress it in the +\pkgopt{xindy} package option. For example: +\begin{verbatim} +\usepackage[xindy={glsnumbers=false}]{glossaries} +\end{verbatim} +Any entry that doesn't go in one of the letter groups or the +number group is placed in the default group. If you want \gls{xindy} +to sort the number group numerically (rather than by a string sort) +then you need to use \gls{xindy}['s] \texttt{numeric-sort} module: +\begin{verbatim} +\GlsAddXdyStyle{numeric-sort} +\end{verbatim} + +If you don't use \texttt{glsnumbers=false}, the default behaviour is to locate +the number group before the \qt{A} letter group. If you are not using a +Roman alphabet, you need to change this using: + + +\begin{definition}[\DescribeMacro\GlsSetXdyFirstLetterAfterDigits] +\cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter} +\end{definition} +where \meta{letter} is the first letter of your alphabet. Take care +if you're using \sty{inputenc} as non-ASCII characters are actually +active characters that expand. (This isn't a problem with the native +UTF-8 engines and \sty{fontspec}.) The starred form will sanitize +the argument to prevent expansion. +Alternatively you can use: + + +\begin{definition}[\DescribeMacro\GlsSetXdyNumberGroupOrder] +\cs{GlsSetXdyNumberGroupOrder}\marg{relative location} +\end{definition} +to change the default +\begin{alltt} +:before \cs{string}"\meta{letter}\cs{string}" +\end{alltt} +to \meta{relative location}. For example: +\begin{verbatim} +\GlsSetXdyNumberGroupOrder{:after \string"Z\string"} +\end{verbatim} +will put the number group after the \qt{Z} letter group. +Again take care of active characters. There's a starred version +that sanitizes the argument (so don't use \cs{string} in it). +\begin{alltt} +\cs{GlsSetXdyNumberGroupOrder}*\{:after "\"O"\} +\end{alltt} + +\begin{important} +Note that these commands have no effect if +\ics{noist} is used or if \ics{makeglossaries} is omitted. +\cs{GlsSetXdyFirstLetterAfterDigits} must be used before +\ics{makeglossaries}.\par +\end{important} + + +\chapter{Defining New Glossaries} +\label{sec:newglossary} + +A new glossary can be defined using: +\begin{definition}[\DescribeMacro{\newglossary}] +\cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\linebreak\marg{title}\oarg{counter} +\end{definition} +where \meta{name} is the label to assign to this glossary. +The arguments \meta{in-ext} and \meta{out-ext} specify the extensions to +give to the input and output files for that glossary, \meta{title} +is the default title for this new glossary and the final optional +argument \meta{counter} specifies which counter to use for the +associated \glspl{numberlist} (see also +\sectionref{sec:numberlists}). The first optional argument specifies +the extension for the \gls{makeindex} (\opt2) or \gls{xindy} (\opt3) +transcript file (this information is only used by +\gls{makeglossaries} which picks up the information from the +auxiliary file). If you use \opt1, the \meta{log-ext}, +\meta{in-ext} and \meta{out-ext} arguments are ignored. + +\begin{important} +The glossary label \meta{name} must not contain any active +characters. It's generally best to stick with just characters that +have category code~11 (typically the non-extended \glspl{latinchar} +for standard \LaTeX). +\end{important} + +There is also a starred version (new to v4.08): +\begin{definition}[\DescribeMacro{\newglossary*}] +\cs{newglossary*}\marg{name}\marg{title}\oarg{counter} +\end{definition} +which is equivalent to +\begin{alltt} +\cs{newglossary}[\meta{name}-glg]\marg{name}\{\meta{name}-gls\}\{\meta{name}-glo\}\ifpdf\linebreak\fi\marg{title}\oarg{counter} +\end{alltt} +or you can also use: +\begin{definition}[\DescribeMacro{\altnewglossary}] +\cs{altnewglossary}\marg{name}\marg{tag}\marg{title}\oarg{counter} +\end{definition} +which is equivalent to +\begin{alltt} +\cs{newglossary}[\meta{tag}-glg]\marg{name}\{\meta{tag}-gls\}\{\meta{tag}-glo\}\marg{title}\oarg{counter} +\end{alltt} + +It may be that you have some terms that are so common +that they don't need to be listed. In this case, you can define +a~special type of glossary that doesn't create any associated files. +This is referred to as an \qt{ignored glossary} and it's ignored by +commands that iterate over all the glossaries, such as +\ics{printglossaries}. To define an ignored glossary, use +\begin{definition}[\DescribeMacro\newignoredglossary] +\cs{newignoredglossary}\marg{name} +\end{definition} +where \meta{name} is the name of the glossary (as above). This +glossary type will automatically be added to the +\pkgopt{nohypertypes} list, since there are no hypertargets for +the entries in an ignored glossary. +(The sample file \samplefile{-entryfmt} defines an ignored glossary.) + +You can test if a glossary is an ignored one using: +\begin{definition}[\DescribeMacro\ifignoredglossary] +\cs{ifignoredglossary}\marg{name}\marg{true}\marg{false} +\end{definition} +This does \meta{true} if \meta{name} was defined as an ignored +glossary, otherwise it does \meta{false}. + +Note that the main (default) glossary is automatically created as: +\begin{verbatim} +\newglossary{main}{gls}{glo}{\glossaryname} +\end{verbatim} +so it can be identified by the label \texttt{main} (unless the +\pkgopt{nomain} package option is used). Using the +\pkgopt{acronym} package option is equivalent to: +\begin{verbatim} +\newglossary[alg]{acronym}{acr}{acn}{\acronymname} +\end{verbatim} +so it can be identified by the label \texttt{acronym}. If you are +not sure whether the \pkgopt{acronym} option has been used, you +can identify the list of acronyms by the command +\DescribeMacro{\acronymtype}\cs{acronymtype} which is set to +\texttt{acronym}, if the \pkgopt{acronym} option has been used, +otherwise it is set to \texttt{main}. Note that if you are using +the main glossary as your list of acronyms, you need to declare +it as a list of acronyms using the package option +\pkgopt{acronymlists}. + +The \pkgopt{symbols} package option creates a new glossary with the +label \texttt{symbols} using: +\begin{verbatim} +\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname} +\end{verbatim} +The \pkgopt{numbers} package option creates a new glossary with +the label \texttt{numbers} using: +\begin{verbatim} +\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname} +\end{verbatim} +The \pkgopt{index} package option creates a new glossary with +the label \texttt{index} using: +\begin{verbatim} +\newglossary[ilg]{index}{ind}{idx}{\indexname} +\end{verbatim} + +\begin{important} +\optsand23: all glossaries must be defined before \ics{makeglossaries} to +ensure that the relevant output files are opened. + +See \sectionref{sec:fixednames} if you want to redefine \cs{glossaryname}, +especially if you are using \sty{babel} or \sty{translator}. +(Similarly for \cs{glssymbolsgroupname} and +\cs{glsnumbersgroupname}.) If you want to redefine \ics{indexname}, +just follow the advice in +\href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=fixnam}{How to +change LaTeX’s \qt{fixed names}}. +\end{important} + +\chapter{Acronyms and Other Abbreviations} +\label{sec:acronyms} + +The \sty{glossaries-extra} package provides superior +abbreviation handling. You may want to consider using that +package instead of the commands described here. + +\begin{important} +Note that although this chapter uses the term \qt{acronym}, you can also +use the commands described here for initialisms or contractions +(as in the case of some of the examples given below). +If the glossary title is no longer applicable (for example, it +should be \qt{Abbreviations} rather than \qt{Acronyms}) then +you can change the title either by redefining \ics{acronymname} (see +\sectionref{sec:languages}) or by using the \gloskey[printglossary]{title} +in the optional argument of \ics{printglossary} (or +\ics{printacronym}). Alternatively consider using the +\sty{glossaries-extra} package's \pkgoptfmt{abbreviations} +option instead. +\end{important} + +You may have noticed in \sectionref{sec:newglosentry} that when you +specify a new entry, you can specify alternate text to use when the +term is \glsd{firstuse} in the document. This provides a +useful means to define abbreviations. For convenience, the +\styfmt{glossaries} package defines the command: +\begin{definition}[\DescribeMacro{\newacronym}] +\cs{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long} +\end{definition} + +This uses \ics{newglossaryentry} to create an entry with the given +label in the glossary given by \ics{acronymtype}. You can specify a +different glossary using the \gloskey{type} key within the optional +argument. The \cs{newacronym} command also uses the \gloskey{long}, +\gloskey{longplural}, \gloskey{short} and \gloskey{shortplural} keys +in \cs{newglossaryentry} to store the long and abbreviated forms and +their plurals. + +Note that the same restrictions on the entry \meta{label} +in \ics{newglossaryentry} also apply to \cs{newacronym} +(see \sectionref{sec:newglosentry}). + +\begin{important} +If you haven't identified the specified glossary type as a list of +acronyms (via the package option +\pkgopt{acronymlists} or the command \ics{DeclareAcronymList}, +see \sectionref{sec:pkgopts-acronym}) \cs{newacronym} will add it to +the list and \emph{reset the display style} for that glossary via +\ics{defglsentryfmt}. If you have a mixture of acronyms and regular +entries within the same glossary, care is needed if you want to +change the display style: you must first identify that glossary as a +list of acronyms and then use \ics{defglsentryfmt} (not redefine +\ics{glsentryfmt}) before defining your entries. +\end{important} + +The optional argument \marg{key-val list} allows you to specify +additional information. Any key that can be used in the second +argument of \ics{newglossaryentry} can also be used here in \meta{key-val +list}. +For example, \gloskey{description} (when used with one of the styles that +require a description, described in +\sectionref{sec:setacronymstyle}) or you can +override plural forms of \meta{abbrv} or \meta{long} using the +\gloskey{shortplural} or \gloskey{longplural} keys. +For example: +\begin{verbatim} +\newacronym[longplural={diagonal matrices}]% + {dm}{DM}{diagonal matrix} +\end{verbatim} +If the \firstuse\ uses the plural form, \verb|\glspl{dm}| will +display: diagonal matrices (DMs). If you want to use +the \gloskey{longplural} or \gloskey{shortplural} keys, I recommend +you use \ics{setacronymstyle} to set the display style rather than +using one of the pre-version 4.02 acronym styles. + +As with \gloskey{plural} and \gloskey{firstplural}, if +\gloskey{longplural} is missing, it's obtained by appended +\ics{glspluralsuffix} to the singular form. The short plural +\gloskey{shortplural} is obtained (is not explicitly set) by appending +\ics{glsacrpluralsuffix} to the short form. These commands may be +changed by the associated language files, but they can't be added to +the usual caption hooks as there's no guarantee when they'll be +expanded (as \hyperref[pluralsuffix]{discussed earlier}). +A different approach is used by \styfmt{glossaries-extra}, which has +category attributes to determine whether or not to append a suffix +when forming the default value of \gloskey{shortplural}. + +Since \ics{newacronym} uses \ics{newglossaryentry}, you can use +commands like \ics{gls} and \ics{glsreset} as with any other +glossary entry. + +\begin{important} +Since \cs{newacronym} sets \verb|type=\acronymtype|, +if you want to load a file containing acronym definitions using +\ics{loadglsentries}\oarg{type}\marg{filename}, the optional argument +\meta{type} will not have an effect unless you explicitly set the +type as \verb|type=\glsdefaulttype| in the optional argument to +\ics{newacronym}. See \sectionref{sec:loadglsentries}. +\end{important} + +\begin{example}{Defining an Abbreviation}{ex:newacronym} +The following defines the abbreviation IDN: +\begin{verbatim} +\newacronym{idn}{IDN}{identification number} +\end{verbatim} +\verb|\gls{idn}| will produce \qt{identification number (IDN)} on +\firstuse\ and \qt{IDN} on subsequent uses. If you want to use one +of the smallcaps acronym styles, described in +\sectionref{sec:setacronymstyle}, you need to use lower case +characters for the shortened form: +\begin{verbatim} +\newacronym{idn}{idn}{identification number} +\end{verbatim} +Now \verb|\gls{idn}| will produce \qt{identification number +(\textsc{idn})} on \firstuse\ and \qt{\textsc{idn}} on subsequent +uses. +\end{example} + +\begin{important} +Avoid nested definitions. +\end{important} + +Recall from the warning in +\sectionref{sec:newglosentry} that you should avoid using +the \glslike\ and \glstextlike\ commands within the value of +keys like \gloskey{text} and \gloskey{first} due to complications +arising from nested links. The same applies to abbreviations +defined using \cs{newacronym}. + +For example, suppose you have defined: +\begin{verbatim} +\newacronym{ssi}{SSI}{server side includes} +\newacronym{html}{HTML}{hypertext markup language} +\end{verbatim} +you may be tempted to do: +\begin{verbatim} +\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}} +\end{verbatim} +\textbf{Don't!} This will break the case-changing commands, such +as \ics{Gls}, it will cause inconsistencies on \firstuse, and, +if hyperlinks are enabled, will cause nested hyperlinks. It will +also confuse the commands used by the entry formatting (such as +\ics{glslabel}). + +Instead, consider doing: +\begin{verbatim} +\newacronym + [description={\gls{ssi} enabled \gls{html}}] + {shtml}{SHTML}{SSI enabled HTML} +\end{verbatim} +or +\begin{verbatim} +\newacronym + [description={\gls{ssi} enabled \gls{html}}] + {shtml}{SHTML} + {server side includes enabled hypertext markup language} +\end{verbatim} +Similarly for the \glstextlike\ commands. + +Other approaches are available with \sty{glossaries-extra}. +See the section \qt{Nested Links} in the \styfmt{glossaries-extra} +user manual. + +\begin{important} +The commands described below are similar to the \glstextlike\ +commands in that they don't modify the \firstuseflag. +However, their display is governed by \ics{defentryfmt} with +\ics{glscustomtext} set as appropriate. All caveats that apply to +the \glstextlike\ commands also apply to the following commands. +(Including the warning immediately above this box.) +\end{important} + +The optional arguments are the same as those for the \glstextlike\ +commands, and there are similar star and plus variants that switch +off or on the hyperlinks. As with the \glstextlike\ commands, the +\gls{linktext} is placed in the argument of \ics{glstextformat}. + +\begin{definition}[\DescribeMacro{\acrshort}] +\cs{acrshort}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This sets the \gls{linktext} to the short form (within the argument +of \ics{acronymfont}) for the entry given by \meta{label}. The short +form is as supplied by the \gloskey{short} key, which +\ics{newacronym} implicitly sets. + +There are also analogous upper case variants: +\begin{definition}[\DescribeMacro{\Acrshort}] +\cs{Acrshort}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\ACRshort}] +\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +There are also plural versions: +\begin{definition}[\DescribeMacro\acrshortpl] +\cs{acrshortpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\Acrshortpl] +\cs{Acrshortpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\ACRshortpl] +\cs{ACRshortpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +The short plural form is as supplied +by the \gloskey{shortplural} key, which \ics{newacronym} implicitly sets. + +\begin{definition}[\DescribeMacro{\acrlong}] +\cs{acrlong}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This sets the \gls{linktext} to the long form for the entry given by +\meta{label}. The long form is as supplied +by the \gloskey{long} key, which \ics{newacronym} implicitly sets. + +There are also analogous upper case variants: +\begin{definition}[\DescribeMacro{\Acrlong}] +\cs{Acrlong}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\ACRlong}] +\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +Again there are also plural versions: +\begin{definition}[\DescribeMacro{\acrlongpl}] +\cs{acrlongpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\Acrlongpl}] +\cs{Acrlongpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\ACRlongpl}] +\cs{ACRlongpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +The long plural form is as supplied by the \gloskey{longplural} key, +which \ics{newacronym} implicitly sets. + +The commands below display the full form of the acronym, but note +that this isn't necessarily the same as the form used on \firstuse. +These full-form commands are shortcuts that use the above commands, +rather than creating the \gls{linktext} from the complete full form. +These full-form commands have star and plus variants and optional +arguments that are passed to the above commands. + +\begin{definition}[\DescribeMacro{\acrfull}] +\cs{acrfull}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This is a shortcut for +\begin{definition}[\DescribeMacro{\acrfullfmt}] +\cs{acrfullfmt}\marg{options}\marg{label}\marg{insert} +\end{definition} +which by default does +\begin{alltt} +\cs{acrfullformat} + \{\cs{acrlong}\oarg{options}\marg{label}\marg{insert}\} + \{\cs{acrshort}\oarg{options}\marg{label}\} +\end{alltt} +where +\begin{definition}[\DescribeMacro\acrfullformat] +\cs{acrfullformat}\marg{long}\marg{short} +\end{definition} +by default does \meta{long} (\meta{short}). This command is now +deprecated for new acronym styles but is used by the default for +backward compatibility if \cs{setacronymstyle} +(\sectionref{sec:setacronymstyle}) hasn't been used. (For further +details of these format commands see \ifpdf +section~\ref*{sec:code:acronym} in \fi the documented code, +\texttt{glossaries-code.pdf}.) + +There are also analogous upper case variants: +\begin{definition}[\DescribeMacro{\Acrfull}] +\cs{Acrfull}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\ACRfull}] +\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +and plural versions: +\begin{definition}[\DescribeMacro\acrfullpl] +\cs{acrfullpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\Acrfullpl] +\cs{Acrfullpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\ACRfullpl] +\cs{ACRfullpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +If you find the above commands too cumbersome to write, you can use +the \pkgopt{shortcuts} package option to activate the shorter +command names listed in \tableref{tab:shortcuts}. + +\begin{table}[htbp] +\caption{Synonyms provided by the package option \pkgoptfmt{shortcuts}} +\label{tab:shortcuts} +\vskip\baselineskip +\centering +\begin{tabular}{ll} +\bfseries Shortcut Command & \bfseries Equivalent Command\\ +\ics{acs} & \ics{acrshort}\\ +\ics{Acs} & \ics{Acrshort}\\ +\ics{acsp} & \ics{acrshortpl}\\ +\ics{Acsp} & \ics{Acrshortpl}\\ +\ics{acl} & \ics{acrlong}\\ +\ics{Acl} & \ics{Acrlong}\\ +\ics{aclp} & \ics{acrlongpl}\\ +\ics{Aclp} & \ics{Acrlongpl}\\ +\ics{acf} & \ics{acrfull}\\ +\ics{Acf} & \ics{Acrfull}\\ +\ics{acfp} & \ics{acrfullpl}\\ +\ics{Acfp} & \ics{Acrfullpl}\\ +\ics{ac} & \ics{gls}\\ +\ics{Ac} & \ics{Gls}\\ +\ics{acp} & \ics{glspl}\\ +\ics{Acp} & \ics{Glspl} +\end{tabular} +\end{table} + +It is also possible to access the long and short forms without +adding information to the glossary using commands analogous to +\ics{glsentrytext} (described in \sectionref{sec:glsnolink}). + +\begin{important} +The commands that convert the first letter to upper case come with +the same caveats as those for analogous commands like +\ics{Glsentrytext} (non-expandable, can't be used in PDF bookmarks, +care needs to be taken if the first letter is an accented character +etc). See \sectionref{sec:glsnolink}. +\end{important} + +The long form can be accessed using: +\begin{definition}[\DescribeMacro{\glsentrylong}] +\cs{glsentrylong}\marg{label} +\end{definition} +or, with the first letter converted to upper case: +\begin{definition}[\DescribeMacro{\Glsentrylong}] +\cs{Glsentrylong}\marg{label} +\end{definition} +Plural forms: +\begin{definition}[\DescribeMacro{\glsentrylongpl}] +\cs{glsentrylongpl}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentrylongpl}] +\cs{Glsentrylongpl}\marg{label} +\end{definition} + +Similarly, to access the short form: +\begin{definition}[\DescribeMacro{\glsentryshort}] +\cs{glsentryshort}\marg{label} +\end{definition} +or, with the first letter converted to upper case: +\begin{definition}[\DescribeMacro{\Glsentryshort}] +\cs{Glsentryshort}\marg{label} +\end{definition} +Plural forms: +\begin{definition}[\DescribeMacro{\glsentryshortpl}] +\cs{glsentryshortpl}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryshortpl}] +\cs{Glsentryshortpl}\marg{label} +\end{definition} + +And the full form can be obtained using: +\begin{definition}[\DescribeMacro{\glsentryfull}] +\cs{glsentryfull}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryfull}] +\cs{Glsentryfull}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glsentryfullpl}] +\cs{glsentryfullpl}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\Glsentryfullpl}] +\cs{Glsentryfullpl}\marg{label} +\end{definition} +These again use \ics{acrfullformat} by default, but +the new styles described in the section below use different +formatting commands. + +\section{Changing the Abbreviation Style} +\label{sec:setacronymstyle} + +It may be that the default style doesn't suit your requirements in +which case you can switch to another style using +\begin{definition}[\DescribeMacro{\setacronymstyle}] +\cs{setacronymstyle}\marg{style name} +\end{definition} +where \meta{style name} is the name of the required style. + +\begin{important} +You must use \cs{setacronymstyle} \emph{before} you define the +acronyms with \cs{newacronym}. +\end{important} + +For example: +\begin{verbatim} +\usepackage[acronym]{glossaries} + +\makeglossaries + +\setacronymstyle{long-sc-short} + +\newacronym{html}{html}{hypertext markup language} +\newacronym{xml}{xml}{extensible markup language} +\end{verbatim} +Unpredictable results can occur if you try to use multiple styles. + +\begin{important} +If you need multiple abbreviation styles, then try +using the \gls{glossaries-extra} package, which has better +abbreviation management. +\end{important} + +Note that unlike the default behaviour of \cs{newacronym}, the +styles used via \cs{setacronymstyle} don't use the \gloskey{first} +or \gloskey{text} keys, but instead they use \ics{defglsentryfmt} to +set a~custom format that uses the \gloskey{long} and \gloskey{short} +keys (or their plural equivalents). This means that these styles +cope better with plurals that aren't formed by simply appending the +singular form with the letter \qt{s}. In fact, most of the predefined +styles use \ics{glsgenacfmt} and modify the definitions of commands +like \ics{genacrfullformat}. + +Note that when you use \cs{setacronymstyle} the \gloskey{name} key +is set to +\begin{definition}[\DescribeMacro{\acronymentry}] +\cs{acronymentry}\marg{label} +\end{definition} +and the \gloskey{sort} key is set to +\begin{definition}[\DescribeMacro{\acronymsort}] +\cs{acronymsort}\marg{short}\marg{long} +\end{definition} +These commands are redefined by the acronym styles. However, you can +redefine them again after the style has been set but before you use +\cs{newacronym}. Protected expansion is performed on \cs{acronymsort} +when the entry is defined. + +\subsection{Predefined Acronym Styles} +\label{sec:predefinedacrstyles} + +The \styfmt{glossaries} package provides a~number of predefined +styles. These styles apply +\begin{definition}[\DescribeMacro{\firstacronymfont}] +\cs{firstacronymfont}\marg{text} +\end{definition} +to the short form on first use and +\begin{definition}[\DescribeMacro{\acronymfont}] +\cs{acronymfont}\marg{text} +\end{definition} +on subsequent use. The styles modify the definition of +\cs{acronymfont} as required, but \ics{firstacronymfont} is only set +once by the package when it's loaded. By default +\ics{firstacronymfont}\marg{text} is the same as +\ics{acronymfont}\marg{text}. +If you want the short form displayed differently on first use, you +can redefine \ics{firstacronymfont} independently of the acronym +style. + +The predefined styles that contain \texttt{sc} in their name (for +example \acrstyle{long-sc-short}) redefine \cs{acronymfont} to use +\ics{textsc}, which means that the short form needs to be specified +in lower case. \ifpdf Remember that \verb|\textsc{abc}| produces +\textsc{abc} but \verb|\textsc{ABC}| produces \textsc{ABC}.\fi + +\hypertarget{boldsc}{}% +\begin{important}% +Some fonts don't support bold smallcaps, so you may need to redefine +\ics{glsnamefont} (see \sectionref{sec:printglossary}) to switch to +medium weight if you are using a glossary style that displays entry +names in bold and you have chosen an acronym style that uses +\ics{textsc}. +\end{important} + +The predefined styles that contain \texttt{sm} in their name +(for example \acrstyle{long-sm-short}) redefine \cs{acronymfont} to +use \ics{textsmaller}. + +\hypertarget{smaller}{}% +\begin{important} +Note that the \styfmt{glossaries} package doesn't define or load any package that +defines \ics{textsmaller}. If you use one of the acronym styles that +set \ics{acronymfont} to \cs{textsmaller} you must +explicitly load the \sty{relsize} package or otherwise define +\cs{textsmaller}. +\end{important} + +The remaining predefined styles redefine \cs{acronymfont}\marg{text} +to simply do its argument \meta{text}. + +\begin{important} +In most cases, the predefined styles adjust \ics{acrfull} and +\ics{glsentryfull} (and their plural and upper case variants) to +reflect the style. The only exceptions to this are the +\acrstyle{dua} and \acrstyle{footnote} styles (and their variants). +\end{important} + +The following styles are supplied by the \styfmt{glossaries} +package: +\begin{itemize} +\item \acrstyle{long-short}, \acrstyle{long-sc-short}, +\acrstyle{long-sm-short}, \acrstyle{long-sp-short}: + +With these three styles, acronyms are displayed in the form +\begin{definition} +\meta{long} (\ics{firstacronymfont}\marg{short}) +\end{definition} +on first use and +\begin{definition} +\ics{acronymfont}\marg{short} +\end{definition} +on subsequent use. +They also set \cs{acronymsort}\marg{short}\marg{long} to just +\meta{short}. This means that the acronyms are sorted according to +their short form. In addition, \cs{acronymentry}\marg{label} is set +to just the short form (enclosed in \cs{acronymfont}) and the +\gloskey{description} key is set to the long form. + +The \acrstyle{long-sp-short} style was introduced in version~4.16 +and uses +\begin{definition}[\DescribeMacro\glsacspace] +\cs{glsacspace}\marg{label} +\end{definition} +for the space between the long and short forms. This defaults to +a~non-breakable space (\verb|~|) if +(\cs{acronymfont}\marg{short}) is less than 3em, otherwise it uses +a~normal space. This may be redefined as required. For example, to +always use a~non-breakable space: +\begin{verbatim} +\renewcommand*{\glsacspace}[1]{~} +\end{verbatim} + +\item \acrstyle{short-long}, \acrstyle{sc-short-long}, +\acrstyle{sm-short-long}: + +These three styles are analogous to the above three styles, except +the display order is swapped to +\begin{definition} +\ics{firstacronymfont}\marg{short} (\meta{long}) +\end{definition} +on first use. + +Note, however, that \ics{acronymsort} and \ics{acronymentry} are the +same as for the \meta{long} (\meta{short}) styles above, so the +acronyms are still sorted according to the short form. + +\item \acrstyle{long-short-desc}, \acrstyle{long-sc-short-desc}, +\acrstyle{long-sm-short-desc}, \acrstyle{long-sp-short-desc}: + +These are like the \acrstyle{long-short}, \acrstyle{long-sc-short}, +\acrstyle{long-sm-short} and \acrstyle{long-sp-short} styles described above, except that the +\gloskey{description} key must be supplied in the optional argument +of \ics{newacronym}. They also redefine \ics{acronymentry} to +\marg{long} (\cs{acronymfont}\marg{short}) and redefine +\ics{acronymsort}\marg{short}\marg{long} to just \meta{long}. +This means that the acronyms are sorted according to the long form, +and in the list of acronyms the name field has the long form +followed by the short form in parentheses. I~recommend you use +a~glossary style such as \glostyle{altlist} with these acronym +styles to allow for the long name field. + +\item \acrstyle{short-long-desc}, \acrstyle{sc-short-long-desc}, +\acrstyle{sm-short-long-desc}: + +These styles are analogous to the above three styles, but the first +use display style is: +\begin{definition} +\cs{firstacronymfont}\marg{short} (\meta{long}) +\end{definition} +The definitions of \cs{acronymsort} and \cs{acronymentry} are the +same as those for \acrstyle{long-short-desc} etc. + +\item \acrstyle{dua}, \acrstyle{dua-desc}: + +With these styles, the \glslike\ commands always display the long form +regardless of whether the entry has been used or not. However, \ics{acrfull} +and \ics{glsentryfull} will display \meta{long} (\cs{acronymfont}\marg{short}). In the case +of \acrstyle{dua}, the \gloskey{name} and \gloskey{sort} keys are set to +the short form and the description is set to the long form. In the +case of \acrstyle{dua-desc}, the \gloskey{name} and \gloskey{sort} +keys are set to the long form and the description is supplied in the +optional argument of \ics{newacronym}. + +\item \acrstyle{footnote}, \acrstyle{footnote-sc}, +\acrstyle{footnote-sm}: + +With these three styles, on first use the \glslike\ commands display: +\begin{definition} +\cs{firstacronymfont}\marg{short}\ics{footnote}\marg{long} +\end{definition} +However, \ics{acrfull} and \ics{glsentryfull} are set to +\cs{acronymfont}\marg{short} (\meta{long}). On subsequent use the display is: +\begin{definition} +\cs{acronymfont}\marg{short} +\end{definition} +The \gloskey{sort} and \gloskey{name} keys are set to +the short form, and the \gloskey{description} is set to the long +form. + +\begin{important} +In order to avoid nested hyperlinks on \firstuse\ the footnote +styles automatically implement \pkgopt[false]{hyperfirst} for the +acronym lists. +\end{important} + +\item \acrstyle{footnote-desc}, \acrstyle{footnote-sc-desc}, +\acrstyle{footnote-sm-desc}: + +These three styles are similar to the previous three styles, but the +description has to be supplied in the optional argument of +\ics{newacronym}. The \gloskey{name} key is set to the long form +followed by the short form in parentheses and the \gloskey{sort} key +is set to the long form. This means that the acronyms will be sorted +according to the long form. In addition, since the \gloskey{name} +will typically be quite wide it's best to choose a glossary style +that can accommodate this, such as \glostyle{altlist}. + +\end{itemize} + +\begin{example}{Adapting a Predefined Acronym Style}{ex:acrstyle} +Suppose I~want to use the \acrstyle{footnote-sc-desc} style, but +I~want the \gloskey{name} key set to the short form followed by the +long form in parentheses and the \gloskey{sort} key set to the short +form. Then I need to specify the \acrstyle{footnote-sc-desc} style: +\begin{verbatim} +\setacronymstyle{footnote-sc-desc} +\end{verbatim} +and then redefine \ics{acronymsort} and \ics{acronymentry}: +\begin{verbatim} +\renewcommand*{\acronymsort}[2]{#1}% sort by short form +\renewcommand*{\acronymentry}[1]{% + \acronymfont{\glsentryshort{#1}}\space (\glsentrylong{#1})}% +\end{verbatim} +(I've used \cs{space} for extra clarity, but you can just use an +actual space instead.) + +Since the default Computer Modern fonts don't support bold +smallcaps, I'm also going to redefine \ics{acronymfont} so that it +always switches to medium weight to ensure the smallcaps setting is +used: +\begin{verbatim} +\renewcommand*{\acronymfont}[1]{\textmd{\scshape #1}} +\end{verbatim} +This isn't necessary if you use a font that supports bold smallcaps. + +The sample file \samplefile{FnAcrDesc} illustrates this +example. +\end{example} + +\subsection{Defining A Custom Acronym Style} +\label{sec:customacronym} + +You may find that the predefined acronyms styles that come with the +\styfmt{glossaries} package don't suit your requirements. In this +case you can define your own style using: +\begin{definition}[\DescribeMacro{\newacronymstyle}] +\cs{newacronymstyle}\marg{style name}\marg{display}\marg{definitions} +\end{definition} +where \meta{style name} is the name of the new style (avoid active +characters). The second argument, \meta{display}, is equivalent to +the mandatory argument of \ics{defglsentryfmt}. You can simply use +\ics{glsgenacfmt} or you can customize the display using commands +like \ics{ifglsused}, \ics{glsifplural} and \ics{glscapscase}. +(See \sectionref{sec:glsdisplay} for further details.) +If the style is likely to be used with a mixed glossary (that is entries in +that glossary are defined both with \ics{newacronym} and +\ics{newglossaryentry}) then you can test if the entry is an acronym +and use \ics{glsgenacfmt} if it is or \ics{glsgenentryfmt} if it +isn't. For example, the \acrstyle{long-short} style sets +\meta{display} as +\begin{verbatim} +\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}% +\end{verbatim} +(You can use \ics{ifglshasshort} instead of \ics{ifglshaslong} to +test if the entry is an acronym if you prefer.) + +The third argument, \meta{definitions}, can be used to redefine the +commands that affect the display style, such as \ics{acronymfont} +or, if \meta{display} uses \cs{glsgenacfmt}, \ics{genacrfullformat} +and its variants. + +Note that \ics{setacronymstyle} redefines \ics{glsentryfull} and +\ics{acrfullfmt} to use \ics{genacrfullformat} (and similarly for +the plural and upper case variants). If this isn't appropriate for the +style (as in the case of styles like \acrstyle{footnote} and +\acrstyle{dua}) \cs{newacronymstyle} should redefine these commands +within \meta{definitions}. + + +Within \cs{newacronymstyle}'s \meta{definitions} argument you +can also redefine +\begin{definition}[\DescribeMacro{\GenericAcronymFields}] +\cs{GenericAcronymFields} +\end{definition} +This is a list of additional fields to be set in \ics{newacronym}. +You can use the following token registers to access the entry label, +long form and short form: \DescribeMacro{\glslabeltok}\cs{glslabeltok}, +\DescribeMacro{\glslongtok}\cs{glslongtok} and +\DescribeMacro{\glsshorttok}\cs{glsshorttok}. As with all \TeX\ +registers, you can access their values by preceding the register +with \ics{the}. For example, the \acrstyle{long-short} style does: +\begin{verbatim} +\renewcommand*{\GenericAcronymFields}{% + description={\the\glslongtok}}% +\end{verbatim} +which sets the \gloskey{description} field to the long form of the +acronym whereas the \acrstyle{long-short-desc} style does: +\begin{verbatim} +\renewcommand*{\GenericAcronymFields}{}% +\end{verbatim} +since the description needs to be specified by the user. + +It may be that you want to define a new acronym style that's based +on an existing style. Within \meta{display} you can use +\begin{definition}[\DescribeMacro\GlsUseAcrEntryDispStyle] +\cs{GlsUseAcrEntryDispStyle}\marg{style name} +\end{definition} +to use the \meta{display} definition from the style given by +\meta{style name}. Within \meta{definitions} you can use +\begin{definition}[\DescribeMacro{\GlsUseAcrStyleDefs}] +\cs{GlsUseAcrStyleDefs}\marg{style name} +\end{definition} +to use the \meta{definitions} from the style given by \meta{style +name}. For example, the \acrstyle{long-sc-short} acronym style is +based on the \acrstyle{long-short} style with minor +modifications (remember to use \verb|##| instead of \verb|#| within +\meta{definitions}): +\begin{verbatim} +\newacronymstyle{long-sc-short}% +{% use the same display as "long-short" + \GlsUseAcrEntryDispStyle{long-short}% +}% +{% use the same definitions as "long-short" + \GlsUseAcrStyleDefs{long-short}% + % Minor modifications: + \renewcommand{\acronymfont}[1]{\textsc{##1}}% + \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}% +} +\end{verbatim} +(\DescribeMacro{\glstextup}\cs{glstextup} is used to cancel the effect +of \ics{textsc}. This defaults to \ics{textulc}, if defined, +otherwise \ics{textup}. For example, the plural of \textsc{svm} +should be rendered as \textsc{svm}s rather than \textsc{svms}.) + +\begin{example}{Defining a Custom Acronym Style}{ex:customacrstyle} +Suppose I want my acronym on \firstuse\ to have the +short form in the text and the long form with the description in a +footnote. Suppose also that I want the short form to be put in small +caps in the main body of the document, but I want it in normal +capitals in the list of acronyms. In my list of acronyms, I want the +long form as the name with the short form in brackets followed by +the description. That is, in the text I want \ics{gls} on \gls{firstuse} +to display: +\begin{display} +\ics{textsc}\marg{abbrv}\cs{footnote}"{"\meta{long}: \meta{description}"}" +\end{display} +on subsequent use: +\begin{display} +\ics{textsc}\marg{abbrv} +\end{display} +and in the list of acronyms, each entry will be displayed in the +form: +\begin{display} +\meta{long} (\meta{short}) \meta{description} +\end{display} + +Let's suppose it's possible that I may have a mixed glossary. I can +check this in the second argument of \ics{newacronymstyle} using: +\begin{verbatim} +\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}% +\end{verbatim} +This will use \ics{glsgenentryfmt} if the entry isn't an acronym, +otherwise it will use \ics{glsgenacfmt}. The third argument +(\meta{definitions}) of +\ics{newacronymstyle} needs to redefine \ics{genacrfullformat} etc +so that the \firstuse\ displays the short form in the text with the +long form in a footnote followed by the description. This is done as +follows (remember to use \verb|##| instead of \verb|#|): +\begin{verbatim} + % No case change, singular first use: + \renewcommand*{\genacrfullformat}[2]{% + \firstacronymfont{\glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + % First letter upper case, singular first use: + \renewcommand*{\Genacrfullformat}[2]{% + \firstacronymfont{\Glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + % No case change, plural first use: + \renewcommand*{\genplacrfullformat}[2]{% + \firstacronymfont{\glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% + % First letter upper case, plural first use: + \renewcommand*{\Genplacrfullformat}[2]{% + \firstacronymfont{\Glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% +\end{verbatim} +If you think it inappropriate for the short form to be capitalised +at the start of a sentence you can change the above to: +\begin{verbatim} + % No case change, singular first use: + \renewcommand*{\genacrfullformat}[2]{% + \firstacronymfont{\glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + % No case change, plural first use: + \renewcommand*{\genplacrfullformat}[2]{% + \firstacronymfont{\glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% + \let\Genacrfullformat\genacrfullformat + \let\Genplacrfullformat\genplacrfullformat +\end{verbatim} +Another variation is to use \ics{Glsentrylong} and +\ics{Glsentrylongpl} in the footnote instead of \ics{glsentrylong} and +\ics{glsentrylongpl}. + +Now let's suppose that commands such as \ics{glsentryfull} and +\ics{acrfull} shouldn't +use a~footnote, but instead use the format: \meta{long} +(\meta{short}). +This means that the style needs to redefine \cs{glsentryfull}, +\ics{acrfullfmt} and their plural and upper case variants. + +First, the non-linking commands: +\begin{verbatim} + \renewcommand*{\glsentryfull}[1]{% + \glsentrylong{##1}\space + (\acronymfont{\glsentryshort{##1}})% + }% + \renewcommand*{\Glsentryfull}[1]{% + \Glsentrylong{##1}\space + (\acronymfont{\glsentryshort{##1}})% + }% + \renewcommand*{\glsentryfullpl}[1]{% + \glsentrylongpl{##1}\space + (\acronymfont{\glsentryshortpl{##1}})% + }% + \renewcommand*{\Glsentryfullpl}[1]{% + \Glsentrylongpl{##1}\space + (\acronymfont{\glsentryshortpl{##1}})% + }% +\end{verbatim} +Now for the linking commands: +\begin{verbatim} + \renewcommand*{\acrfullfmt}[3]{% + \glslink[##1]{##2}{% + \glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + \renewcommand*{\Acrfullfmt}[3]{% + \glslink[##1]{##2}{% + \Glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + \renewcommand*{\ACRfullfmt}[3]{% + \glslink[##1]{##2}{% + \MakeTextUppercase{% + \glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + }% + \renewcommand*{\acrfullplfmt}[3]{% + \glslink[##1]{##2}{% + \glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + \renewcommand*{\Acrfullplfmt}[3]{% + \glslink[##1]{##2}{% + \Glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + \renewcommand*{\ACRfullplfmt}[3]{% + \glslink[##1]{##2}{% + \MakeTextUppercase{% + \glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + }% +\end{verbatim} +(This may cause problems with long hyperlinks, in which case adjust +the definitions so that, for example, only the short form is inside +the argument of \ics{glslink}.) + +The style also needs to redefine \ics{acronymsort} so that the +acronyms are sorted according to the long form: +\begin{verbatim} + \renewcommand*{\acronymsort}[2]{##2}% +\end{verbatim} +If you prefer them to be sorted according to the short form you can +change the above to: +\begin{verbatim} + \renewcommand*{\acronymsort}[2]{##1}% +\end{verbatim} +The acronym font needs to be set to \ics{textsc} and the plural +suffix adjusted so that the \qt{s} suffix in the plural short form +doesn't get converted to smallcaps: +\begin{verbatim} + \renewcommand*{\acronymfont}[1]{\textsc{##1}}% + \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}% +\end{verbatim} +There are a number of ways of dealing with the format in the list of +acronyms. The simplest way is to redefine \ics{acronymentry} to the +long form followed by the upper case short form in parentheses: +\begin{verbatim} + \renewcommand*{\acronymentry}[1]{% + \Glsentrylong{##1}\space + (\MakeTextUppercase{\glsentryshort{##1}})}% +\end{verbatim} +(I've used \ics{Glsentrylong} instead of \ics{glsentrylong} to +capitalise the name in the glossary.) + +An alternative approach is to set \ics{acronymentry} to just the +long form and redefine \ics{GenericAcronymFields} to set the +\gloskey{symbol} key to the short form and use a glossary style that +displays the symbol in parentheses after the \gloskey{name} (such as +the \glostyle{tree} style) like this: +\begin{verbatim} + \renewcommand*{\acronymentry}[1]{\Glsentrylong{##1}}% + \renewcommand*{\GenericAcronymFields}{% + symbol={\protect\MakeTextUppercase{\the\glsshorttok}}}% +\end{verbatim} +I'm going to use the first approach and set +\ics{GenericAcronymFields} to do nothing: +\begin{verbatim} + \renewcommand*{\GenericAcronymFields}{}% +\end{verbatim} + +Finally, this style needs to switch off hyperlinks on first use to +avoid nested links: +\begin{verbatim} + \glshyperfirstfalse +\end{verbatim} +Putting this all together: +\begin{verbatim} +\newacronymstyle{custom-fn}% new style name +{% + \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}% +}% +{% + \renewcommand*{\GenericAcronymFields}{}% + \glshyperfirstfalse + \renewcommand*{\genacrfullformat}[2]{% + \firstacronymfont{\glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + \renewcommand*{\Genacrfullformat}[2]{% + \firstacronymfont{\Glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + \renewcommand*{\genplacrfullformat}[2]{% + \firstacronymfont{\glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% + \renewcommand*{\Genplacrfullformat}[2]{% + \firstacronymfont{\Glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% + \renewcommand*{\glsentryfull}[1]{% + \glsentrylong{##1}\space + (\acronymfont{\glsentryshort{##1}})% + }% + \renewcommand*{\Glsentryfull}[1]{% + \Glsentrylong{##1}\space + (\acronymfont{\glsentryshort{##1}})% + }% + \renewcommand*{\glsentryfullpl}[1]{% + \glsentrylongpl{##1}\space + (\acronymfont{\glsentryshortpl{##1}})% + }% + \renewcommand*{\Glsentryfullpl}[1]{% + \Glsentrylongpl{##1}\space + (\acronymfont{\glsentryshortpl{##1}})% + }% + \renewcommand*{\acrfullfmt}[3]{% + \glslink[##1]{##2}{% + \glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + \renewcommand*{\Acrfullfmt}[3]{% + \glslink[##1]{##2}{% + \Glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + \renewcommand*{\ACRfullfmt}[3]{% + \glslink[##1]{##2}{% + \MakeTextUppercase{% + \glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + }% + \renewcommand*{\acrfullplfmt}[3]{% + \glslink[##1]{##2}{% + \glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + \renewcommand*{\Acrfullplfmt}[3]{% + \glslink[##1]{##2}{% + \Glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + \renewcommand*{\ACRfullplfmt}[3]{% + \glslink[##1]{##2}{% + \MakeTextUppercase{% + \glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + }% + \renewcommand*{\acronymfont}[1]{\textsc{##1}}% + \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}% + \renewcommand*{\acronymsort}[2]{##2}% + \renewcommand*{\acronymentry}[1]{% + \Glsentrylong{##1}\space + (\MakeTextUppercase{\glsentryshort{##1}})}% +} +\end{verbatim} + +Now I need to specify that I want to use this new style: +\begin{verbatim} +\setacronymstyle{custom-fn} +\end{verbatim} +I also need to use a glossary style that suits this acronym style, +for example \glostyle{altlist}: +\begin{verbatim} +\setglossarystyle{altlist} +\end{verbatim} + +Once the acronym style has been set, I can define my acronyms: +\begin{verbatim} +\newacronym[description={set of tags for use in +developing hypertext documents}]{html}{html}{Hyper +Text Markup Language} + +\newacronym[description={language used to describe the +layout of a document written in a markup language}]{css} +{css}{Cascading Style Sheet} +\end{verbatim} + +The sample file \samplefile{-custom-acronym} illustrates this +example. +\end{example} + +\begin{example}{Italic and Upright Abbreviations}{ex:font-abbr} +Suppose I~want to have some abbreviations in italic and some that +just use the surrounding font. Hard-coding this into the +\meta{short} argument of \cs{newacronym} can cause complications. + +This example uses \ics{glsaddstoragekey} to add an extra field that +can be used to store the formatting declaration (such as \cs{em}). +\begin{verbatim} +\glsaddstoragekey{font}{}{\entryfont} +\end{verbatim} +This defines a~new field/key called \texttt{font}, which defaults to +nothing if it's not explicitly set. This also defines a command +called \cs{entryfont} that's analogous to \cs{glsentrytext}. A~new +style is then created to format abbreviations that access this field. + +There are two ways to do this. The first is to create a style that +doesn't use \ics{glsgenacfmt} but instead provides a~modified +version that doesn't use \cs{acronymfont}\marg{short} +but instead uses +\verb|{|\cs{entryfont}\verb|{\glslabel}|\meta{short}\verb|}|. +The full format given by commands such as \cs{genacrfullformat} +need to be similarly adjusted. For example: +\begin{verbatim} + \renewcommand*{\genacrfullformat}[2]{% + \glsentrylong{##1}##2\space + ({\entryfont{##1}\glsentryshort{##1}})% + }% +\end{verbatim} +This will deal with commands like \ics{gls} but not commands like +\ics{acrshort} which still use \ics{acronymfont}. Another approach +is to redefine \cs{acronymfont} to look up the required font +declaration. Since \cs{acronymfont} doesn't take the entry label as +an argument, the following will only work if \cs{acronymfont} is +used in a~context where the label is provided by \ics{glslabel}. +This is true in \cs{gls}, \cs{acrshort} and \cs{acrfull}. The +redefinition is now: +\begin{verbatim} +\renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}#1}}% +\end{verbatim} +So the new style can be defined as: +\begin{verbatim} +\newacronymstyle{long-font-short} +{% + \GlsUseAcrEntryDispStyle{long-short}% +} +{% + \GlsUseAcrStyleDefs{long-short}% + \renewcommand*{\genacrfullformat}[2]{% + \glsentrylong{##1}##2\space + ({\entryfont{##1}\glsentryshort{##1}})% + }% + \renewcommand*{\Genacrfullformat}[2]{% + \Glsentrylong{##1}##2\space + ({\entryfont{##1}\glsentryshort{##1}})% + }% + \renewcommand*{\genplacrfullformat}[2]{% + \glsentrylongpl{##1}##2\space + ({\entryfont{##1}\glsentryshortpl{##1}})% + }% + \renewcommand*{\Genplacrfullformat}[2]{% + \Glsentrylongpl{##1}##2\space + ({\entryfont{##1}\glsentryshortpl{##1}})% + }% + \renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}##1}}% + \renewcommand*{\acronymentry}[1]{{\entryfont{##1}\glsentryshort{##1}}}% +} +\end{verbatim} +Remember the style needs to be set before defining the entries: +\begin{verbatim} +\setacronymstyle{long-font-short} +\end{verbatim} + +The complete document is contained in the sample file +\samplefile{-font-abbr}. +\end{example} + +Some writers and publishing houses have started to drop full stops +(periods) from upper case initials but may still retain them for +lower case abbreviations, while others may still use them for both +upper and lower case. This can cause complications. Chapter~12 of +\emph{The \TeX{}book} discusses the spacing between words but, +briefly, the default behaviour of \TeX\ is to assume that an upper +case character followed by a~full stop and space is an abbreviation, +so the space is the default inter-word space whereas a~lower case +character followed by a~full stop and space is a word occurring at +the end of a~sentence. In the event that this isn't true, you need +to make a~manual adjustment using \verb*| | (back slash space) in +place of just a~space character for an inter-word mid-sentence space +and use \verb|\@| before the full stop to indicate the end of the +sentence. + +For example: +\begin{verbatim} +I was awarded a B.Sc. and a Ph.D. (From the same place.) +\end{verbatim} +is typeset as +\begin{display} +I was awarded a B.Sc. and a Ph.D. (From the same place.) +\end{display} +The spacing is more noticeable with the typewriter font: +\begin{verbatim} +\ttfamily +I was awarded a B.Sc. and a Ph.D. (From the same place.) +\end{verbatim} +is typeset as +\begin{display}\ttfamily +I was awarded a B.Sc. and a Ph.D. (From the same place.) +\end{display} +The lower case letter at the end of ``B.Sc.''\ is confusing \TeX\ +into thinking that the full stop after it marks the end of the +sentence. Whereas the upper case letter at the end of ``Ph.D.'' has +confused \TeX\ into thinking that the following full stop is just +part of the abbreviation. These can be corrected: +\begin{verbatim} +I was awarded a B.Sc.\ and a Ph.D\@. (From the same place.) +\end{verbatim} + +This situation is a bit problematic for \styfmt{glossaries}. The +full stops can form part of the \meta{short} argument of +\cs{newacronym} and the \verb*|B.Sc.\ | part can be dealt with by +remembering to add \verb*|\ | (for example, \verb*|\gls{bsc}\ |) +but the end of sentence case is more troublesome as you need to omit +the sentence terminating full stop (to avoid two dots) which can +make the source code look a little strange but you also need to +adjust the space factor, which is usually done by inserting \cs{@} +before the full stop. + +The next example shows one way of achieving this. +(Note that the supplemental \gls{glossaries-extra} package provides a much +simpler way of doing this, which you may prefer to use. See the +\href{http://www.dickimaw-books.com/gallery/sample-initialisms.shtml}{initialisms +example}.) + +\begin{example}{Abbreviations with Full Stops (Periods)}{ex:dotabbr} +As from version 4.16, there's now a hook (\ics{glspostlinkhook}) +that's called at the very end of the \glslike\ and \glstextlike\ +commands. This can be redefined to check if the following character +is a full stop. The \sty{amsgen} package (which is automatically +loaded by \styfmt{glossaries}) provides an internal command +called \cs{new@ifnextchar} that can be used to determine if the +given character appears next. (For more information see the +\sty{amsgen} documentation.) + +It's possible that I~may also want acronyms or contractions in my +document, so I~need some way to differentiate between them. +Here I'm going to use the same method as in +example~\ref{ex:addstoragekey} where a~new field is defined +to indicate the type of abbreviation: +\begin{verbatim} +\glsaddstoragekey{abbrtype}{word}{\abbrtype} + +\newcommand*{\newabbr}[1][]{\newacronym[abbrtype=initials,#1]} +\end{verbatim} +Now I just use \ics{newacronym} for the acronyms, for example, +\begin{verbatim} +\newacronym{laser}{laser}{light amplification by stimulated +emission of radiation} +\end{verbatim} +and my new command \cs{newabbr} for initials, for example, +\begin{verbatim} +\newabbr{eg}{e.g.}{exempli gratia} +\newabbr{ie}{i.e.}{id est} +\newabbr{bsc}{B.Sc.}{Bachelor of Science} +\newabbr{ba}{B.A.}{Bachelor of Arts} +\newabbr{agm}{A.G.M.}{annual general meeting} +\end{verbatim} +Within \cs{glspostlinkhook} the entry's label can be accessed using +\ics{glslabel} and \ics{ifglsfieldeq} can be used to determine if +the current entry has the new \texttt{abbrtype} field set to +\qt{initials}. If it doesn't, then nothing needs to happen, but if +it does, a~check is performed to see if the next character is a~full +stop. If it is, this signals the end of a~sentence otherwise it's +mid-sentence. + +Remember that internal commands within the document file (rather +than in a~class or package) need to be placed between +\ics{makeatletter} and \ics{makeatother}: +\begin{verbatim} +\makeatletter +\renewcommand{\glspostlinkhook}{% + \ifglsfieldeq{\glslabel}{abbrtype}{initials}% + {\new@ifnextchar.\doendsentence\doendword} + {}% +} +\makeatother +\end{verbatim} +In the event that a full stop is found \cs{doendsentence} is +performed but it will be followed by the full stop, which needs to +be discarded. Otherwise \cs{doendword} will be done but it won't be +followed by a full stop so there's nothing to discard. The +definitions for these commands are: +\begin{verbatim} +\newcommand{\doendsentence}[1]{\spacefactor=10000{}} +\newcommand{\doendword}{\spacefactor=1000{}} +\end{verbatim} +Now, I can just do \verb|\gls{bsc}| mid-sentence and +\verb|\gls{phd}.| at the end of the sentence. The terminating full +stop will be discarded in the latter case, but it won't be discarded +in, say, \verb|\gls{laser}.| as that doesn't have the +\texttt{abbrtype} field set to \qt{initials}. + +This also works on first use when the style is set to one of the +\meta{long} (\meta{short}) styles but it will fail with the +\meta{short} (\meta{long}) styles as in this case the terminating +full stop shouldn't be discarded. Since \ics{glspostlinkhook} is +used after the \firstuseflag\ has been unset for the entry, this +can't be fixed by simply checking with \ics{ifglsused}. One possible +solution to this is to redefine \ics{glslinkpostsetkeys} to check +for the \firstuseflag\ and define a macro that can then be used in +\ics{glspostlinkhook}. + +The other thing to consider is what to do with plurals. One +possibility is to check for plural use within \cs{doendsentence} +(using \ics{glsifplural}) and put the full stop back if the plural +has been used. + +The complete document is contained in the sample file +\samplefile{-dot-abbr}. +\end{example} + +\section{Displaying the List of Acronyms} +\label{sec:disploa} + +The list of acronyms is just like any other type of glossary and can +be displayed on its own using: +\begin{description} +\itempar{\opt1:} +\begin{alltt} +\ics{printnoidxglossary}[type=\ics{acronymtype}] +\end{alltt} + +\itempar{\optsand23:} +\begin{alltt} +\ics{printglossary}[type=\ics{acronymtype}] +\end{alltt} + +(If you use the +\pkgopt{acronym} package option you can also use +\begin{alltt} +\ics{printacronyms}\oarg{options} +\end{alltt} +as a synonym for +\begin{alltt} +\ics{printglossary}[type=\ics{acronymtype},\meta{options}] +\end{alltt} +See \sectionref{sec:pkgopts-acronym}.) + +\end{description} +Alternatively the list of acronyms can be displayed with all the other +glossaries using: +\begin{description} +\item[\opt1:] \ics{printnoidxglossaries} + +\item[\optsand23:] \ics{printglossaries} +\end{description} + +However, care must be taken to choose a glossary style that's +appropriate to your acronym style. +Alternatively, you can define your own custom style (see +\sectionref{sec:newglossarystyle} for further details). + +\section{Upgrading From the glossary Package} +\label{sec:oldacronym} + +Users of the obsolete \sty{glossary} package may recall that +the syntax used to define new acronyms has changed with the +replacement \styfmt{glossaries} package. In addition, the old +\sty{glossary} package created the command +\cs{}\meta{acr-name} when defining the acronym \meta{acr-name}. + +In order to facilitate migrating from the old package to the new +one, the \styfmt{glossaries} package\footnote{as from version 1.18} +provides the command: +\begin{definition}[\DescribeMacro{\oldacronym}] +\cs{oldacronym}\oarg{label}\marg{abbrv}\marg{long}\marg{key-val list} +\end{definition} +This uses the same syntax as the \sty{glossary} package's +method of defining acronyms. It is equivalent to: +\begin{display} +\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long} +\end{display} +In addition, \ics{oldacronym} also defines the commands +\cs{}\meta{label}, which is equivalent to \ics{gls}\marg{label}, +and \cs{}\meta{label}\texttt{*}, which is equivalent to +\ics{Gls}\marg{label}. If \meta{label} is omitted, \meta{abbrv} +is used. Since commands names must consist only of alphabetical +characters, \meta{label} must also only consist of alphabetical +characters. Note that \cs{}\meta{label} doesn't allow you to use +the first optional argument of \ics{gls} or \ics{Gls} --- you will +need to explicitly use \ics{gls} or \ics{Gls} to change the +settings. + +\begin{important} +Recall that, in general, \LaTeX\ ignores spaces following command +names consisting of alphabetical characters. This is also true for +\cs{}\meta{label} unless you additionally load the +\sty{xspace} package, but be aware that there are some issues with +using \sty{xspace}.\footnotemark +\end{important} +\footnotetext{See David Carlisle's explanation in +\url{http://tex.stackexchange.com/questions/86565/drawbacks-of-xspace}} + +The \styfmt{glossaries} package doesn't load the \sty{xspace} package +since there are both advantages and disadvantages to using +\ics{xspace} in \cs{}\meta{label}. If you don't use the +\sty{xspace} package you need to explicitly force a space using +\verb*|\ | (backslash space) however you can follow \cs{}\meta{label} +with additional text in square brackets (the final optional +argument to \ics{gls}). If you use the \sty{xspace} package +you don't need to escape the spaces but you can't use +the optional argument to insert text (you will have to explicitly +use \ics{gls}). + +To illustrate this, suppose I define the acronym \qt{abc} as +follows: +\begin{verbatim} +\oldacronym{abc}{example acronym}{} +\end{verbatim} +This will create the command \cs{abc} and its starred version +\cs{abc*}. \Tableref{tab:xspace} illustrates the effect of +\cs{abc} (on subsequent use) according to whether or not the +\sty{xspace} package has been loaded. As can be seen from the +final row in the table, the \sty{xspace} package prevents the +optional argument from being recognised. + +\begin{table}[htbp] +\caption[The effect of using xspace]{The effect of using +\styfmt{xspace} with \cs{oldacronym}} +\label{tab:xspace} +\vskip\baselineskip +\centering +\begin{tabular}{lll} +\bfseries Code & \bfseries With \styfmt{xspace} & +\bfseries Without \styfmt{xspace}\\ +\verb|\abc.| & abc. & abc.\\ +\verb|\abc xyz| & abc xyz & abcxyz\\ +\verb|\abc\ xyz| & abc xyz & abc xyz\\ +\verb|\abc* xyz| & Abc xyz & Abc xyz\\ +\verb|\abc['s] xyz| & abc ['s] xyz & abc's xyz +\end{tabular} +\par +\end{table} + +\chapter{Unsetting and Resetting Entry Flags} +\label{sec:glsunset} + +When using the \glslike\ commands it is +possible that you may want to use the value given by the +\gloskey{first} key, even though you have already \glslink{firstuse}{used} the glossary +entry. Conversely, you may want to use the value given by the +\gloskey{text} key, even though you haven't used the glossary entry. +The former can be achieved by one of the following commands: +\begin{definition}[\DescribeMacro{\glsreset}] +\cs{glsreset}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glslocalreset}] +\cs{glslocalreset}\marg{label} +\end{definition} +while the latter can be achieved by one of the following commands: +\begin{definition}[\DescribeMacro{\glsunset}] +\cs{glsunset}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glslocalunset}] +\cs{glslocalunset}\marg{label} +\end{definition} +You can also reset or unset all entries for a given glossary or list of +glossaries using: +\begin{definition}[\DescribeMacro{\glsresetall}] +\cs{glsresetall}\oarg{glossary list} +\end{definition} +\begin{definition}[\DescribeMacro{\glslocalresetall}] +\cs{glslocalresetall}\oarg{glossary list} +\end{definition} +\begin{definition}[\DescribeMacro{\glsunsetall}] +\cs{glsunsetall}\oarg{glossary list} +\end{definition} +\begin{definition}[\DescribeMacro{\glslocalunsetall}] +\cs{glslocalunsetall}\oarg{glossary list} +\end{definition} +where \meta{glossary list} is a comma-separated list of +glossary labels. If omitted, all defined glossaries are assumed +(except for the ignored ones). +For example, to reset all entries in the main glossary and the +list of acronyms: +\begin{verbatim} +\glsresetall[main,acronym] +\end{verbatim} + +You can determine whether an entry's \gls{firstuseflag} is set using: +\begin{definition}[\DescribeMacro{\ifglsused}] +\cs{ifglsused}\marg{label}\marg{true part}\marg{false part} +\end{definition} +where \meta{label} is the label of the required entry. If the +entry has been used, \meta{true part} will be done, otherwise +\meta{false part} will be done. + +\begin{important} +Be careful when using \glslike\ commands within an +environment or command argument that gets processed multiple times +as it can cause unwanted side-effects when the first use displayed +text is different from subsequent use. +\end{important} + +For example, the \env{frame} environment in \cls{beamer} processes +its argument for each overlay. This means that the \firstuseflag\ +will be unset on the first overlay and subsequent overlays will use +the non-first use form. + +Consider the following example: +\begin{verbatim} +\documentclass{beamer} + +\usepackage{glossaries} + +\newacronym{svm}{SVM}{support vector machine} + +\begin{document} + +\begin{frame} + \frametitle{Frame 1} + + \begin{itemize} + \item<+-> \gls{svm} + \item<+-> Stuff. + \end{itemize} +\end{frame} + +\end{document} +\end{verbatim} + +On the first overlay, \verb|\gls{svm}| produces \qt{support vector +machine (SVM)} and then unsets the \firstuseflag. When the second +overlay is processed, \verb|\gls{svm}| now produces \qt{SVM}, which +is unlikely to be the desired effect. I~don't know anyway around +this and I can only offer two suggestions. + +Firstly, unset all acronyms at the start of the document and +explicitly use \ics{acrfull} when you want the full version to be +displayed: +\begin{verbatim} +\documentclass{beamer} + +\usepackage{glossaries} + +\newacronym{svm}{SVM}{support vector machine} + +\glsunsetall + +\begin{document} +\begin{frame} + \frametitle{Frame 1} + + \begin{itemize} + \item<+-> \acrfull{svm} + \item<+-> Stuff. + \end{itemize} +\end{frame} +\end{document} +\end{verbatim} + +Secondly, explicitly reset each acronym on first use: +\begin{verbatim} +\begin{frame} + \frametitle{Frame 1} + + \begin{itemize} + \item<+-> \glsreset{svm}\gls{svm} + \item<+-> Stuff. + \end{itemize} +\end{frame} +\end{verbatim} +These are non-optimal, but the \cls{beamer} class is too complex for +me to provide a programmatic solution. Other potentially problematic +environments are some \env{tabular}-like environments (but not +\env{tabular} itself) that process the contents in order to work out +the column widths and then reprocess the contents to do the actual +typesetting. + +The \sty{amsmath} environments, such as \env{align}, also process +their contents multiple times, but the \styfmt{glossaries} package now +checks for this. For \sty{tabularx}, you need to explicitly patch it +by placing \cs{glspatchtabularx} in the preamble (or anywhere +before the problematic use of \envfmt{tabularx}). + +\section{Counting the Number of Times an Entry has been Used (First Use +Flag Unset)} +\label{sec:enableentrycount} + +As from version 4.14, it's now possible to keep track of how many +times an entry is used. That is, how many times the \firstuseflag\ +is unset. Note that the supplemental \gls{glossaries-extra} package improves +this function and also provides per-unit counting, which isn't +available with the \styfmt{glossaries} package. + +\begin{important} +This function is disabled by default as it adds extra +overhead to the document build time and also switches +\ics{newglossaryentry} (and therefore \ics{newacronym}) into +a~preamble-only command. +\end{important} + +To enable this function, use +\begin{definition}[\DescribeMacro\glsenableentrycount] +\cs{glsenableentrycount} +\end{definition} +before defining your entries. This adds two extra (internal) fields +to entries: \texttt{currcount} and \texttt{prevcount}. + +The \texttt{currcount} field keeps track of how many times +\cs{glsunset} is used within the document. A~local unset (using +\cs{glslocalunset}) performs a~local rather than global increment to +\texttt{currcount}. Remember that not all commands use +\cs{glsunset}. Only the \glslike\ commands do this. The reset +commands \cs{glsreset} and \cs{glslocalreset} reset this field back +to zero (where \cs{glslocalreset} performs a~local change). + +The \texttt{prevcount} field stores the final value of the +\texttt{currcount} field \emph{from the previous run}. This value is +read from the \texttt{.aux} file at the beginning of the +\env{document} environment. + +You can access these fields using +\begin{definition}[\DescribeMacro\glsentrycurrcount] +\cs{glsentrycurrcount}\marg{label} +\end{definition} +for the \texttt{currcount} field, and +\begin{definition}[\DescribeMacro\glsentryprevcount] +\cs{glsentryprevcount}\marg{label} +\end{definition} +for the \texttt{prevcount} field. \textbf{These commands are +only defined if you have used \cs{glsenableentrycount}.} + +For example: +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\makeglossaries + +\glsenableentrycount + +\newglossaryentry{apple}{name=apple,description={a fruit}} + +\begin{document} +Total usage on previous run: \glsentryprevcount{apple}. + +\gls{apple}. \gls{apple}. \glsadd{apple}\glsentrytext{apple}. +\glslink{apple}{apple}. \glsdisp{apple}{apple}. \Gls{apple}. + +Number of times apple has been used: \glsentrycurrcount{apple}. +\end{document} +\end{verbatim} +On the first \LaTeX\ run, \verb|\glsentryprevcount{apple}| +produces~0. At the end of the document, +\verb|\glsentrycurrcount{apple}| produces~4. This is because +the only commands that have incremented the entry count are those +that use \cs{glsunset}. That is: \cs{gls}, \cs{glsdisp} and +\cs{Gls}. The other commands used in the above example, \cs{glsadd}, +\cs{glsentrytext} and \cs{glslink}, don't use \cs{glsunset} so they +don't increment the entry count. On the \emph{next} \LaTeX\ run, +\verb|\glsentryprevcount{apple}| now produces~4 as that was the +value of the \texttt{currcount} field for the \texttt{apple} entry +at the end of the document on the previous run. + +When you enable the entry count using \cs{glsenableentrycount}, you +also enable the following commands: +\begin{definition}[\DescribeMacro\cgls] +\cs{cgls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(no case-change, singular) +\begin{definition}[\DescribeMacro\cglspl] +\cs{cglspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(no case-change, plural) +\begin{definition}[\DescribeMacro\cGls] +\cs{cGls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(first letter uppercase, singular), and +\begin{definition}[\DescribeMacro\cGlspl] +\cs{cGlspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(first letter uppercase, plural). +These all have plus and starred variants like the analogous +\cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl} commands. + +If you don't use \cs{glsenableentrycount}, these commands behave +like \cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl}, +respectively, only there will be a warning that you haven't enabled +entry counting. If you have enabled entry counting with +\cs{glsenableentrycount} then these commands test if +\cs{glsentryprevcount}\marg{label} equals~1. If it doesn't then the +analogous \cs{gls} etc will be used. If it does, then the first optional +argument will be ignored and +\begin{alltt} +\meta{cs format}\marg{label}\marg{insert}\cs{glsunset}\marg{label} +\end{alltt} +will be performed, where \meta{cs format} is a command that takes +two arguments. The command used depends whether you have used +\cs{cgls}, \cs{cglspl}, \cs{cGls} or \cs{cGlspl}. + +\begin{definition}[\DescribeMacro\cglsformat] +\cs{cglsformat}\marg{label}\marg{insert} +\end{definition} +This command is used by \cs{cgls} and defaults to +\begin{alltt} +\cs{glsentrylong}\marg{label}\meta{insert} +\end{alltt} +if the entry given by +\meta{label} has a~long form or +\begin{alltt} +\cs{glsentryfirst}\marg{label}\meta{insert} +\end{alltt} +otherwise. + +\begin{definition}[\DescribeMacro\cglsplformat] +\cs{cglsplformat}\marg{label}\marg{insert} +\end{definition} +This command is used by \cs{cglspl} and defaults to +\begin{alltt} +\cs{glsentrylongpl}\marg{label}\meta{insert} +\end{alltt} +if the entry given by +\meta{label} has a~long form or +\begin{alltt} +\cs{glsentryfirstplural}\marg{label}\meta{insert} +\end{alltt} +otherwise. + +\begin{definition}[\DescribeMacro\cGlsformat] +\cs{cGlsformat}\marg{label}\marg{insert} +\end{definition} +This command is used by \cs{cGls} and defaults to +\begin{alltt} +\cs{Glsentrylong}\marg{label}\meta{insert} +\end{alltt} +if the entry given by \meta{label} has a~long form or +\begin{alltt} +\cs{Glsentryfirst}\marg{label}\meta{insert} +\end{alltt} +otherwise. + +\begin{definition}[\DescribeMacro\cGlsplformat] +\cs{cGlsplformat}\marg{label}\marg{insert} +\end{definition} +This command is used by \cs{cGlspl} and defaults to +\begin{alltt} +\cs{Glsentrylongpl}\marg{label}\meta{insert} +\end{alltt} +if the entry given by \meta{label} has a~long form or +\begin{alltt} +\cs{Glsentryfirstplural}\marg{label}\meta{insert} +\end{alltt} +otherwise. + +This means that if the previous count for the given entry was~1, the +entry won't be hyperlinked with the \cs{cgls}-like commands and they +won't add a~line to the external glossary file. If you haven't used +any of the other commands that add information to glossary file +(such as \cs{glsadd} or the \glstextlike\ commands) then the entry +won't appear in the glossary. + +Remember that since these commands use \cs{glsentryprevcount} you +need to run \LaTeX\ twice to ensure they work correctly. The +document build order is now (at least): \texttt{(pdf)latex}, +\texttt{(pdf)latex}, \texttt{makeglossaries}, \texttt{(pdf)latex}. + +\begin{example}{Don't index entries that are only used once}{sec:entrycount} +In this example, the abbreviations that have only been used once (on the previous run) +only have their long form shown with \cs{cgls}. +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage[acronym]{glossaries} +\makeglossaries + +\glsenableentrycount + +\setacronymstyle{long-short} + +\newacronym{html}{HTML}{hypertext markup language} +\newacronym{css}{CSS}{cascading style sheets} +\newacronym{xml}{XML}{extensible markup language} +\newacronym{sql}{SQL}{structured query language} +\newacronym{rdbms}{RDBMS}{relational database management system} +\newacronym{rdsms}{RDSMS}{relational data stream management system} + +\begin{document} +These entries are only used once: \cgls{sql}, \cgls{rdbms}, +\cgls{xml}. These entries are used multiple times: +\cgls{html}, \cgls{html}, \cgls{css}, \cgls{css}, \cgls{css}, +\cgls{rdsms}, \cgls{rdsms}. + +\printglossaries +\end{document} +\end{verbatim} +After a complete document build (\texttt{latex}, \texttt{latex}, +\texttt{makeglossaries}, \texttt{latex}) the list of abbrevaitions only +includes the entries HTML, CSS and RDSMS. The entries SQL, RDBMS and +XML +only have their long forms displayed and don't have a~hyperlink. +\end{example} + +Remember that if you don't like typing \cs{cgls} you can create a +synonym. For example +\begin{verbatim} +\let\ac\cgls +\end{verbatim} + +\chapter{Glossary Styles} +\label{sec:styles} + +Glossaries vary from lists that simply contain a symbol with a terse +description to lists of terms or phrases with lengthy descriptions. +Some glossaries may have terms with associated symbols. Some may +have hierarchical entries. There is therefore no single style that +fits every type of glossary. The \styfmt{glossaries} package comes +with a number of pre-defined glossary styles, described in +\sectionref{sec:predefinedstyles}. You can choose one of these that +best suits your type of glossary or, if none of them suit your +document, you can defined your own style (see +\sectionref{sec:newglossarystyle}). There are some examples +of glossary styles available at +\url{http://www.dickimaw-books.com/gallery/#glossaries}. + +The glossary style can be set using the \gloskey[printglossary]{style} key in the optional +argument to \ics{printnoidxglossary} (\opt1) or \ics{printglossary} +(\optsand23) or using the command: +\begin{definition}[\DescribeMacro{\setglossarystyle}] +\cs{setglossarystyle}\marg{style-name} +\end{definition} +(before the glossary is displayed). + +Some of the predefined glossary styles may also be set using the \pkgopt{style} +package option, it depends if the package in which they are defined +is automatically loaded by the \styfmt{glossaries} package. + +You can use the lorum ipsum dummy entries provided in the +accompanying +\texttt{example-glossaries-*.tex} files (described in +\sectionref{sec:lipsum}) to test the different styles. + +\section{Predefined Styles} +\label{sec:predefinedstyles} + +The predefined styles can +accommodate numbered level~0 (main) and level~1 entries. See the +package options \pkgopt{entrycounter}, \pkgopt{counterwithin} and +\pkgopt{subentrycounter} described in +\sectionref{sec:pkgopts-printglos}. There is a summary +of available styles in \tableref{tab:styles}. +You can view samples of all the predefined styles at +\url{http://www.dickimaw-books.com/gallery/glossaries-styles/}. +Note that \gls{glossaries-extra} provides additional styles +in the supplementary packages \sty{glossary-bookindex} and +\sty{glossary-longnoloc}. See the \gls{glossaries-extra} manual for +further details. + +\begin{important} +Note that the group styles (such as \glostyle{listgroup}) will +have unexpected results if used with the \pkgopt[def]{sort} +or \pkgopt[use]{sort} options. If you don't sort your entries +alphabetically, it's best to set the \pkgopt{nogroupskip} +package option to prevent odd vertical gaps appearing. +\end{important} + +The group title is obtained using \cs{glsgetgrouptitle}\marg{label}, +which is described in \sectionref{sec:newglossarystyle}. + +\begin{table}[htbp] +\caption[Glossary Styles]{Glossary Styles. An asterisk in the style +name indicates anything that matches that doesn't match any +previously listed style (e.g.\ \texttt{long3col*} +matches \glostyle{long3col}, \glostyle{long3colheader}, +\glostyle{long3colborder} and \glostyle{long3colheaderborder}). +A maximum level of 0 indicates a flat glossary (sub-entries +are displayed in the same way as main entries). Where the maximum +level is given as --- there is no limit, but note that +\gls{makeindex} (\opt2) imposes a limit of 2 sub-levels. If the +homograph column is checked, then the name is not displayed for +sub-entries. If the symbol column is checked, then the symbol will +be displayed.} +\label{tab:styles} +\vskip\baselineskip +\centering +\begin{tabular}{lccc} +\bfseries Style & \bfseries Maximum Level & +\bfseries Homograph & \bfseries Symbol\\ +\ttfamily listdotted & 0 & & \\ +\ttfamily sublistdotted & 1 & & \\ +\ttfamily list* & 1 & \tick & \\ +\ttfamily altlist* & 1 & \tick & \\ +\ttfamily long*3col* & 1 & \tick & \\ +\ttfamily long4col* & 1 & \tick & \tick \\ +\ttfamily altlong*4col* & 1 & \tick & \tick \\ +\ttfamily long* & 1 & \tick & \\ +\ttfamily super*3col* & 1 & \tick & \\ +\ttfamily super4col* & 1 & \tick & \tick \\ +\ttfamily altsuper*4col* & 1 & \tick & \tick \\ +\ttfamily super* & 1 & \tick & \\ +\ttfamily *index* & 2 & & \tick\\ +\ttfamily treenoname* & --- & \tick & \tick\\ +\ttfamily *alttree* & --- & & \tick\\ +\ttfamily *tree* & --- & & \tick\\ +\ttfamily inline & 1 & \tick & +\end{tabular} +\par +\end{table} + +The tabular-like styles that allow multi-line descriptions and page +lists use the length \DescribeMacro{\glsdescwidth}\cs{glsdescwidth} +to set the width of the description column and the length +\DescribeMacro{\glspagelistwidth}\cs{glspagelistwidth} to set the +width of the page list column.\footnote{These lengths will not be +available if you use both the \pkgopt{nolong} and \pkgopt{nosuper} +package options or if you use the \pkgopt{nostyles} package option +unless you explicitly load the relevant package.} +These will need to be changed using \cs{setlength} if the glossary +is too wide. Note that the \glostyle{long4col} and +\glostyle{super4col} styles (and their header and border variations) +don't use these lengths as they are designed for single line +entries. Instead you should use the analogous \glostyle{altlong4col} +and \glostyle{altsuper4col} styles. If you want to +explicitly create a line-break within a multi-line description in +a tabular-like style it's better to use \ics{newline} instead of +\verb|\\|. + +\begin{important} +Remember that a cell within a tabular-like environment can't +be broken across a page, so even if a tabular-like style, such as +\glostyle{long}, allows multilined descriptions, you'll probably encounter +page-breaking problems if you have entries with long descriptions. +You may want to consider using the \glostyle{alttree} style instead. +\end{important} + +Note that if you use the \gloskey[printglossary]{style} key in the +optional argument to \ics{printnoidxglossary} (\opt1) or +\ics{printglossary} (\optsand23), it will override any +previous style settings for the given glossary, so if, for example, +you do +\begin{verbatim} +\renewcommand*{\glsgroupskip}{} +\printglossary[style=long] +\end{verbatim} +then the new definition of \ics{glsgroupskip} will not have an affect +for this glossary, as \cs{glsgroupskip} is redefined by +\verb|style=long|. Likewise, \ics{setglossarystyle} will also +override any previous style definitions, so, again +\begin{verbatim} +\renewcommand*{\glsgroupskip}{} +\setglossarystyle{long} +\end{verbatim} +will reset \cs{glsgroupskip} back to its default definition for the +named glossary style (\glostyle{long} in this case). If you want to +modify the styles, either use \ics{newglossarystyle} (described +in the next section) or make the modifications after +\ics{setglossarystyle}, e.g.: +\begin{verbatim} +\setglossarystyle{long} +\renewcommand*{\glsgroupskip}{} +\end{verbatim} +As from version 3.03, you can now use the package option +\pkgopt{nogroupskip} to suppress the gap between groups for the +default styles instead of redefining \cs{glsgroupskip}. + +All the styles except for the three- and four-column styles and the +\glostyle{listdotted} style use the command +\begin{definition}[\DescribeMacro{\glspostdescription}] +\cs{glspostdescription} +\end{definition} +after the description. This simply displays a full stop by default. +To eliminate this full stop (or replace it with something else, say, +a comma) you will need to redefine \cs{glspostdescription} before +the glossary is displayed. Alternatively, you can suppress it for a +given entry by placing \ics{nopostdesc} in the entry's description. +Note that \ics{longnewglossaryentry} puts \cs{nopostdesc} at the end +of the description. The \sty{glossaries-extra} package provides a +starred version that doesn't. + +As from version 3.03 you can now use the package option +\pkgopt{nopostdot} to suppress this full stop. This is the better +option if you want to use the \sty{glossaries-extra} package. +The \sty{glossaries-extra-stylemods} package provides some +adjustments some of to the predefined styles listed here, allowing +for greater flexibility. See the \sty{glossaries-extra} +documentation for further details. + +\subsection{List Styles} +\label{sec:liststyles} + +The styles described in this section are all defined in the package +\sty{glossary-list}. Since they all use the \env{description} +environment, they are governed by the same parameters as that +environment. These styles all ignore the entry's symbol. Note that +these styles will automatically be available unless you use the +\pkgopt{nolist} or \pkgopt{nostyles} package options. + +\begin{important} +Note that, except for the \glostyle{listdotted} style, these +list styles are incompatible with \sty{classicthesis}. They +may also be incompatible with other classes or packages that +modify the \env{description} environment. +\end{important} + +\begin{description} +\item[list] The \glostyle{list} style uses the \env{description} +environment. The entry name is placed in the optional argument of +the \ics{item} command (so it will usually appear in bold by default). The +description follows, and then the associated \gls{numberlist} for +that entry. The symbol is ignored. If the entry has child entries, +the description and number list follows (but not the name) for each +child entry. Groups are separated using \ics{indexspace}. + +The closest matching non-list style is the \glostyle{index} style. + +\item[listgroup] The \glostyle{listgroup} style is like +\glostyle{list} but the glossary groups have headings +obtained using \cs{glsgetgrouptitle}\marg{label}, +which is described in \sectionref{sec:newglossarystyle}. + +\item[listhypergroup] The \glostyle{listhypergroup} style is like +\glostyle{listgroup} but has a navigation line at the start of the +glossary with links to each group that is present in the glossary. +This requires an additional run through \LaTeX\ to ensure the group +information is up to date. In the navigation line, each group is +separated by +\begin{definition}[\DescribeMacro{\glshypernavsep}] +\cs{glshypernavsep} +\end{definition} +which defaults to a vertical bar with a space on either side. For +example, to simply have a space separating each group, do: +\begin{verbatim} +\renewcommand*{\glshypernavsep}{\space} +\end{verbatim} + +Note that the hyper-navigation line is now (as from version 1.14) +set inside the optional argument to \ics{item} instead of after it +to prevent a spurious space at the start. This can cause a problem +if the navigation line is too long. +As from v4.22, if you need to adjust this, you can redefine +\begin{definition}[\DescribeMacro\glslistnavigationitem] +\cs{glslistnavigationitem}\marg{navigation line} +\end{definition} +The default definition is \cs{item}\oarg{navigation line} but may +be redefined independently of setting the style. For example: +\begin{verbatim} +\renewcommand*{\glslistnavigationitem}[1]{\item \textbf{#1}} +\end{verbatim} + +You may prefer to use the tree-like styles, such as +\glostyle{treehypergroup} instead. + +\item[altlist] The \glostyle{altlist} style is like \glostyle{list} +but the description starts on the line following the name. (As +with the \glostyle{list} style, the symbol is ignored.) Each child +entry starts a new line, but as with the \glostyle{list} style, +the name associated with each child entry is ignored. + +The closest matching non-list style is the \glostyle{index} +style with the following adjustment: +\begin{verbatim} +\renewcommand{\glstreepredesc}{% + \glstreeitem\parindent\hangindent} +\end{verbatim} + + +\item[altlistgroup] The \glostyle{altlistgroup} style is like +\glostyle{altlist} but the glossary groups have headings. + +\item[altlisthypergroup] The \glostyle{altlisthypergroup} style is like +\glostyle{altlistgroup} but has a set of links to the glossary +groups. The navigation line is the same as that for +\glostyle{listhypergroup}, described above. + +\item[listdotted] This style uses the \env{description} +environment.\footnote{This style was supplied by Axel~Menzel.} Each +entry starts with \verb|\item[]|, followed by the name followed by a +dotted line, followed by the description. Note that this style +ignores both the \gls{numberlist} and the symbol. The length +\begin{definition}[\DescribeMacro{\glslistdottedwidth}] +\cs{glslistdottedwidth} +\end{definition} +governs where the description should start. This is a flat style, so +child entries are formatted in the same way as the parent entries. + +A non-list alternative is to use the \glostyle{index} style +with +\begin{verbatim} +\renewcommand{\glstreepredesc}{\dotfill} +\renewcommand{\glstreechildpredesc}{\dotfill} +\end{verbatim} +Note that this doesn't use \cs{glslistdottedwidth} and causes +the description to be flush-right and will display the +symbol, if provided. (It also doesn't suppress +the \gls*{numberlist}, but that can be achieved with the +\pkgopt{nonumberlist} option.) + +\item[sublistdotted] This is a variation on the \glostyle{listdotted} +style designed for hierarchical glossaries. The main entries +have just the name displayed. The sub entries are displayed in +the same manner as \glostyle{listdotted}. Unlike the +\glostyle{listdotted} style, this style is incompatible with +\sty{classicthesis}. +\end{description} + + +\subsection{Longtable Styles} +\label{sec:longstyles} + +The styles described in this section are all defined in the package +\sty{glossary-long}. Since they all use the \env{longtable} +environment, they are governed by the same parameters as that +environment. Note that these styles will automatically be available +unless you use the \pkgopt{nolong} or \pkgopt{nostyles} package +options. These styles fully justify the description and page list +columns. If you want ragged right formatting instead, use the +analogous styles described in \sectionref{sec:longraggedstyles}. +If you want to incorporate rules from the \sty{booktabs} package, +try the styles described in \sectionref{sec:longbooktabsstyles}. + +\begin{description} +\item[long] The \glostyle{long} style uses the \env{longtable} +environment (defined by the \sty{longtable} package). It has two +columns: the first column contains the entry's name and the second +column contains the description followed by the \gls{numberlist}. +The entry's symbol is ignored. +Sub groups are separated with a blank row. The width of the +first column is governed by the widest entry in that column. The +width of the second column is governed by the length +\ics{glsdescwidth}. Child entries have a similar format to the +parent entries except that their name is suppressed. + +\item[longborder] The \glostyle{longborder} style is like +\glostyle{long} but has horizontal and vertical lines around it. + +\item[longheader] The \glostyle{longheader} style is like +\glostyle{long} but has a header row. + +\item[longheaderborder] The \glostyle{longheaderborder} style is +like \glostyle{longheader} but has horizontal and vertical lines +around it. + +\item[long3col] The \glostyle{long3col} style is like +\glostyle{long} but has three columns. The first column contains +the entry's name, the second column contains the description +and the third column contains the \gls{numberlist}. +The entry's symbol is ignored. The width of the +first column is governed by the widest entry in that column, the +width of the second column is governed by the length +\ics{glsdescwidth}, and the width of the third column is governed by the +length \ics{glspagelistwidth}. + +\item[long3colborder] The \glostyle{long3colborder} style is like +the \glostyle{long3col} style but has horizontal and vertical +lines around it. + +\item[long3colheader] The \glostyle{long3colheader} style is like +\glostyle{long3col} but has a header row. + +\item[long3colheaderborder] The \glostyle{long3colheaderborder} style is +like \glostyle{long3colheader} but has horizontal and vertical lines +around it. + +\item[long4col] The \glostyle{long4col} style is like +\glostyle{long3col} but has an additional column in which the +entry's associated symbol appears. This style is used for brief +single line descriptions. The column widths are governed by the +widest entry in the given column. Use \glostyle{altlong4col} for +multi-line descriptions. + +\item[long4colborder] The \glostyle{long4colborder} style is like +the \glostyle{long4col} style but has horizontal and vertical +lines around it. + +\item[long4colheader] The \glostyle{long4colheader} style is like +\glostyle{long4col} but has a header row. + +\item[long4colheaderborder] The \glostyle{long4colheaderborder} style is +like \glostyle{long4colheader} but has horizontal and vertical lines +around it. + +\item[altlong4col] The \glostyle{altlong4col} style is like +\glostyle{long4col} but allows multi-line descriptions and page +lists. The width of the description column is governed by the +length \ics{glsdescwidth} and the width of the page list column is +governed by the length \ics{glspagelistwidth}. The widths of the +name and symbol columns are governed by the widest entry in the +given column. + +\item[altlong4colborder] The \glostyle{altlong4colborder} style is like +the \glostyle{long4colborder} but allows multi-line descriptions and +page lists. + +\item[altlong4colheader] The \glostyle{altlong4colheader} style is like +\glostyle{long4colheader} but allows multi-line descriptions and +page lists. + +\item[altlong4colheaderborder] The \glostyle{altlong4colheaderborder} +style is like \glostyle{long4colheaderborder} but allows multi-line +descriptions and page lists. +\end{description} + + +\subsection{Longtable Styles (Ragged Right)} +\label{sec:longraggedstyles} + +The styles described in this section are all defined in the package +\sty{glossary-longragged}. These styles are analogous to those +defined in \sty{glossary-long} but the multiline columns are left +justified instead of fully justified. Since these styles all use the +\env{longtable} environment, they are governed by the same +parameters as that environment. The \sty{glossary-longragged} +package additionally requires the \sty{array} package. Note that +these styles will only be available if you explicitly load +\sty{glossary-longragged}: +\begin{verbatim} +\usepackage{glossaries} +\usepackage{glossary-longragged} +\end{verbatim} +Note that you can't set these styles using the \pkgopt{style} +package option since the styles aren't defined until after +the \styfmt{glossaries} package has been loaded. +If you want to incorporate rules from the \sty{booktabs} package, +try the styles described in \sectionref{sec:longbooktabsstyles}. + +\begin{description} +\item[longragged] The \glostyle{longragged} style has two +columns: the first column contains the entry's name and the second +column contains the (left-justified) description followed by the +\gls{numberlist}. The entry's symbol is ignored. +Sub groups are separated with a blank row. The width of the +first column is governed by the widest entry in that column. The +width of the second column is governed by the length +\ics{glsdescwidth}. Child entries have a similar format to the +parent entries except that their name is suppressed. + +\item[longraggedborder] The \glostyle{longraggedborder} style is like +\glostyle{longragged} but has horizontal and vertical lines around it. + +\item[longraggedheader] The \glostyle{longraggedheader} style is like +\glostyle{longragged} but has a header row. + +\item[longraggedheaderborder] The \glostyle{longraggedheaderborder} +style is like \glostyle{longraggedheader} but has horizontal and +vertical lines around it. + +\item[longragged3col] The \glostyle{longragged3col} style is like +\glostyle{longragged} but has three columns. The first column +contains the entry's name, the second column contains the (left +justified) description and the third column contains the (left +justified) \gls{numberlist}. The entry's symbol is ignored. The +width of the first column is governed by the widest entry in that +column, the width of the second column is governed by the length +\ics{glsdescwidth}, and the width of the third column is governed by +the length \ics{glspagelistwidth}. + +\item[longragged3colborder] The \glostyle{longragged3colborder} +style is like the \glostyle{longragged3col} style but has horizontal +and vertical lines around it. + +\item[longragged3colheader] The \glostyle{longragged3colheader} style is like +\glostyle{longragged3col} but has a header row. + +\item[longragged3colheaderborder] The \glostyle{longragged3colheaderborder} style is +like \glostyle{longragged3colheader} but has horizontal and vertical lines +around it. + +\item[altlongragged4col] The \glostyle{altlongragged4col} style is +like \glostyle{longragged3col} but has an additional column in which +the entry's associated symbol appears. The width of the description +column is governed by the length \ics{glsdescwidth} and the width of +the page list column is governed by the length +\ics{glspagelistwidth}. The widths of the name and symbol columns +are governed by the widest entry in the given column. + +\item[altlongragged4colborder] The +\glostyle{altlongragged4colborder} style is like the +\glostyle{altlongragged4col} but has horizontal and vertical lines +around it. + +\item[altlongragged4colheader] The +\glostyle{altlongragged4colheader} style is like +\glostyle{altlongragged4col} but has a header row. + +\item[altlongragged4colheaderborder] The +\glostyle{altlongragged4colheaderborder} style is like +\glostyle{altlongragged4colheader} but has horizontal and vertical +lines around it. + +\end{description} + +\subsection{Longtable Styles (\styfmt{booktabs})} +\label{sec:longbooktabsstyles} + +The styles described in this section are all defined in the package +\sty{glossary-longbooktabs}. + +Since these styles all use the +\env{longtable} environment, they are governed by the same +parameters as that environment. The \sty{glossary-longbooktabs} +package automatically loads the \sty{glossary-long} +(\sectionref{sec:longstyles}) +and \sty{glossary-longragged} (\sectionref{sec:longraggedstyles}) packages. Note that +these styles will only be available if you explicitly load +\sty{glossary-longbooktabs}: +\begin{verbatim} +\usepackage{glossaries} +\usepackage{glossary-longbooktabs} +\end{verbatim} +Note that you can't set these styles using the \pkgopt{style} +package option since the styles aren't defined until after +the \styfmt{glossaries} package has been loaded. + +These styles are similar to the +\qt{header} styles in the \sty{glossary-long} and +\sty{glossary-ragged} packages, but they add the rules +provided by the \sty{booktabs} package, \ics{toprule}, \ics{midrule} and +\ics{bottomrule}. Additionally these styles patch the +\env{longtable} environment to check for instances of the group +skip occurring at a page break. If you don't want this patch to +affect any other use of \env{longtable} in your document, you can +scope the effect by only setting the style through the +\gloskey[printglossary]{style} key in the optional argument of +\cs{printglossary}. (The \pkgopt{nogroupskip} package option +is checked by these styles.) + +Alternatively, you can restore the original \env{longtable} +behaviour with: +\begin{definition}[\DescribeMacro\glsrestoreLToutput] +\cs{glsrestoreLToutput} +\end{definition} +For more information about the patch, see the documented code +(\texttt{glossaries-code.pdf}). + +\begin{description} +\item[\glostyle{long-booktabs}] This style is similar to +the \glostyle{longheader} style but adds rules above and below the +header (\cs{toprule} and \cs{midrule}) and inserts a rule at the +bottom of the table (\cs{bottomrule}). + +\item[\glostyle{long3col-booktabs}] This style is similar to +the \glostyle{long3colheader} style but adds rules as per +\glostyle{long-booktabs}. + +\item[\glostyle{long4col-booktabs}] This style is similar to +the \glostyle{long4colheader} style but adds rules as above. + +\item[\glostyle{altlong4col-booktabs}] This style is similar to +the \glostyle{altlong4colheader} style but adds rules as above. + +\item[\glostyle{longragged-booktabs}] This style is similar to +the \glostyle{longraggedheader} style but adds rules as above. + +\item[\glostyle{longragged3col-booktabs}] This style is similar to +the \glostyle{longragged3colheader} style but adds rules as above. + +\item[\glostyle{altlongragged4col-booktabs}] This style is similar to +the \glostyle{altlongragged4colheader} style but adds rules as above. + +\end{description} + +\subsection{Supertabular Styles} +\label{sec:superstyles} + +The styles described in this section are all defined in the package +\sty{glossary-super}. Since they all use the \env{supertabular} +environment, they are governed by the same parameters as that +environment. Note that these styles will automatically be available +unless you use the \pkgopt{nosuper} or \pkgopt{nostyles} package +options. In general, the \env{longtable} environment is better, +but there are some circumstances where it is better to use +\env{supertabular}.\footnote{e.g.\ with the \sty{flowfram} +package.} These styles fully justify the description and page list +columns. If you want ragged right formatting instead, use the +analogous styles described in \sectionref{sec:superraggedstyles}. + +\begin{description} +\item[super] The \glostyle{super} style uses the \env{supertabular} +environment (defined by the \sty{supertabular} package). It has two +columns: the first column contains the entry's name and the second +column contains the description followed by the \gls{numberlist}. +The entry's symbol is ignored. +Sub groups are separated with a blank row. The width of the +first column is governed by the widest entry in that column. The +width of the second column is governed by the length +\ics{glsdescwidth}. Child entries have a similar format to the +parent entries except that their name is suppressed. + +\item[superborder] The \glostyle{superborder} style is like +\glostyle{super} but has horizontal and vertical lines around it. + +\item[superheader] The \glostyle{superheader} style is like +\glostyle{super} but has a header row. + +\item[superheaderborder] The \glostyle{superheaderborder} style is +like \glostyle{superheader} but has horizontal and vertical lines +around it. + +\item[super3col] The \glostyle{super3col} style is like +\glostyle{super} but has three columns. The first column contains +the entry's name, the second column contains the description +and the third column contains the \gls{numberlist}. The +entry's symbol is ignored. The width of the +first column is governed by the widest entry in that column. The +width of the second column is governed by the length +\ics{glsdescwidth}. The width of the third column is governed by the +length \ics{glspagelistwidth}. + +\item[super3colborder] The \glostyle{super3colborder} style is like +the \glostyle{super3col} style but has horizontal and vertical +lines around it. + +\item[super3colheader] The \glostyle{super3colheader} style is like +\glostyle{super3col} but has a header row. + +\item[super3colheaderborder] The \glostyle{super3colheaderborder} style +is like the \glostyle{super3colheader} style but has horizontal and vertical +lines around it. + +\item[super4col] The \glostyle{super4col} style is like +\glostyle{super3col} but has an additional column in which the +entry's associated symbol appears. This style is designed for +entries with brief single line descriptions. The column widths are governed by the +widest entry in the given column. Use \glostyle{altsuper4col} +for multi-line descriptions. + +\item[super4colborder] The \glostyle{super4colborder} style is like +the \glostyle{super4col} style but has horizontal and vertical +lines around it. + +\item[super4colheader] The \glostyle{super4colheader} style is like +\glostyle{super4col} but has a header row. + +\item[super4colheaderborder] The \glostyle{super4colheaderborder} style +is like the \glostyle{super4colheader} style but has horizontal and vertical +lines around it. + +\item[altsuper4col] The \glostyle{altsuper4col} style is like +\glostyle{super4col} but allows multi-line descriptions and page +lists. +The width of the description column is governed by the length +\ics{glsdescwidth} and the width of the page list column is +governed by the length \ics{glspagelistwidth}. The width of the name +and symbol columns is governed by the widest entry in the +given column. + +\item[altsuper4colborder] The \glostyle{altsuper4colborder} style is like +the \glostyle{super4colborder} style but allows multi-line descriptions +and page lists. + +\item[altsuper4colheader] The \glostyle{altsuper4colheader} style is like +\glostyle{super4colheader} but allows multi-line descriptions and +page lists. + +\item[altsuper4colheaderborder] The \glostyle{altsuper4colheaderborder} +style is like \glostyle{super4colheaderborder} but allows multi-line +descriptions and page lists. +\end{description} + + +\subsection{Supertabular Styles (Ragged Right)} +\label{sec:superraggedstyles} + +The styles described in this section are all defined in the package +\sty{glossary-superragged}. These styles are analogous to those +defined in \sty{glossary-super} but the multiline columns are left +justified instead of fully justified. Since these styles all use the +\env{supertabular} environment, they are governed by the same +parameters as that environment. The \sty{glossary-superragged} +package additionally requires the \sty{array} package. Note that +these styles will only be available if you explicitly load +\sty{glossary-superragged}: +\begin{verbatim} +\usepackage{glossaries} +\usepackage{glossary-superragged} +\end{verbatim} +Note that you can't set these styles using the \pkgopt{style} +package option since the styles aren't defined until after +the \styfmt{glossaries} package has been loaded. + +\begin{description} +\item[superragged] The \glostyle{superragged} style uses the +\env{supertabular} environment (defined by the +\sty{supertabular} package). It has two columns: the first column +contains the entry's name and the second column contains the (left +justified) description followed by the \gls{numberlist}. The +entry's symbol is ignored. Sub groups are separated with a blank +row. The width of the first column is governed by the widest entry +in that column. The width of the second column is governed by the +length \ics{glsdescwidth}. Child entries have a similar format to +the parent entries except that their name is suppressed. + +\item[superraggedborder] The \glostyle{superraggedborder} style is +like \glostyle{superragged} but has horizontal and vertical lines +around it. + +\item[superraggedheader] The \glostyle{superraggedheader} style is +like \glostyle{superragged} but has a header row. + +\item[superraggedheaderborder] The +\glostyle{superraggedheaderborder} style is like +\glostyle{superraggedheader} but has horizontal and vertical lines +around it. + +\item[superragged3col] The \glostyle{superragged3col} style is like +\glostyle{superragged} but has three columns. The first column +contains the entry's name, the second column contains the (left +justified) description and the third column contains the (left +justified) \gls{numberlist}. The entry's symbol is ignored. The +width of the first column is governed by the widest entry in that +column. The width of the second column is governed by the length +\ics{glsdescwidth}. The width of the third column is governed by the +length \ics{glspagelistwidth}. + +\item[superragged3colborder] The \glostyle{superragged3colborder} +style is like the \glostyle{superragged3col} style but has +horizontal and vertical lines around it. + +\item[superragged3colheader] The \glostyle{superragged3colheader} +style is like \glostyle{superragged3col} but has a header row. + +\item[superragged3colheaderborder] The +\glostyle{superragged3colheaderborder} style is like +\glostyle{superragged3colheader} but has horizontal and vertical +lines around it. + +\item[altsuperragged4col] The \glostyle{altsuperragged4col} style is +like \glostyle{superragged3col} but has an additional column in +which the entry's associated symbol appears. The column widths for +the name and symbol column are governed by the widest entry in the +given column. + +\item[altsuperragged4colborder] The +\glostyle{altsuperragged4colborder} style is like the +\glostyle{altsuperragged4col} style but has horizontal and vertical +lines around it. + +\item[altsuperragged4colheader] The +\glostyle{altsuperragged4colheader} style is like +\glostyle{altsuperragged4col} but has a header row. + +\item[altsuperragged4colheaderborder] The +\glostyle{altsuperragged4colheaderborder} style is like +\glostyle{altsuperragged4colheader} but has horizontal and vertical +lines around it. + +\end{description} + +\subsection{Tree-Like Styles} +\label{sec:treestyles} + +The styles described in this section are all defined in the package +\sty{glossary-tree}. These styles are designed for hierarchical +glossaries but can also be used with glossaries that don't have +sub-entries. These styles will display the entry's symbol if it +exists. Note that these styles will automatically be available +unless you use the \pkgopt{notree} or \pkgopt{nostyles} package +options. + +These styles all format the entry name using: +\begin{definition}[\DescribeMacro\glstreenamefmt] +\cs{glstreenamefmt}\marg{name} +\end{definition} +This defaults to \cs{textbf}\marg{name}, but note that \meta{name} +includes \ics{glsnamefont} so the bold setting in \cs{glstreenamefont} +may be counteracted by another font change in \cs{glsnamefont} (or +in \cs{acronymfont}). The tree-like styles that also display the +header use +\begin{definition}[\DescribeMacro\glstreegroupheaderfmt] +\cs{glstreegroupheaderfmt}\marg{text} +\end{definition} +to format the heading. This defaults to +\cs{glstreenamefmt}\marg{text}. The tree-like styles that display +navigation links to the groups (such as \glostyle{indexhypergroup}), format +the navigation line using +\begin{definition}[\DescribeMacro\glstreenavigationfmt] +\cs{glstreenavigationfmt}\marg{text} +\end{definition} +which defaults to \cs{glstreenamefmt}\marg{text}. Note that this is +different from \cs{glslistnavigationitem}, provided with the styles +such as \glostyle{listhypergroup}, as that also includes \cs{item}. + +With the exception of the \glostyle{alttree} style (and those +derived from it), the space before the description for top-level +entries is produced with +\begin{definition}[\DescribeMacro\glstreepredesc] +\cs{glstreepredesc} +\end{definition} +This defaults to \cs{space}. + +With the exception of the \glostyle{treenoname} and +\glostyle{alttree} styles (and those derived from them), the +space before the description for child +entries is produced with +\begin{definition}[\DescribeMacro\glstreechildpredesc] +\cs{glstreechildpredesc} +\end{definition} +This defaults to \cs{space}. + +\begin{important} +Most of these styles are not designed for multi-paragraph +descriptions. (The \glostyle{tree} style isn't too bad for +multi-paragraph top-level entry descriptions, or you can use the +\glostyle{index} style with the adjustment shown below.) +\end{important} + +\begin{description} +\item[index] The \glostyle{index} style is similar to the way +indices are usually formatted in that it has a hierarchical +structure up to three levels (the main level plus two sub-levels). +The name is typeset in bold, and if the symbol is present it is set +in parentheses after the name and before the description. +Sub-entries are indented and also include the name, the symbol +in brackets (if present) and the description. Groups are separated +using \ics{indexspace}. + +Each main level item is started with +\begin{definition}[\DescribeMacro\glstreeitem] +\cs{glstreeitem} +\end{definition} +The level~1 entries are started with +\begin{definition}[\DescribeMacro\glstreesubitem] +\cs{glstreesubitem} +\end{definition} + +The level~2 entries are started with +\begin{definition}[\DescribeMacro\glstreesubsubitem] +\cs{glstreesubsubitem} +\end{definition} + +Note that the \glostyle{index} style automatically sets +\begin{verbatim} +\let\item\glstreeitem +\let\subitem\glstreesubitem +\let\subsubitem\glstreesubsubitem +\end{verbatim} +at the start of the glossary for backward compatibility. + +The \glostyle{index} style isn't suitable for multi-paragraph +descriptions, but this limitation can be overcome by redefining +the above commands. For example: +\begin{verbatim} +\renewcommand{\glstreeitem}{% + \parindent0pt\par\hangindent40pt + \everypar{\parindent50pt\hangindent40pt}} +\end{verbatim} + +\item[indexgroup] The \glostyle{indexgroup} style is similar to +the \glostyle{index} style except that each group has a heading +obtained using \cs{glsgetgrouptitle}\marg{label}, +which is described in \sectionref{sec:newglossarystyle}. + +\item[indexhypergroup] The \glostyle{indexhypergroup} style is like +\glostyle{indexgroup} but has a set of links to the glossary +groups. The navigation line is the same as that for +\glostyle{listhypergroup}, described above, but is formatted using +\cs{glstreenavigationfmt}. + +\item[tree] The \glostyle{tree} style is similar to the +\glostyle{index} style except that it can have arbitrary levels. +(Note that \gls{makeindex} is limited to three levels, so +you will need to use \gls{xindy} if you want more than +three levels.) Each sub-level is indented by +\DescribeMacro{\glstreeindent}\cs{glstreeindent}. Note that the +name, symbol (if present) and description are placed in the +same paragraph block. If you want the name to be apart from the +description, use the \glostyle{alttree} style instead. (See below.) + +\item[treegroup] The \glostyle{treegroup} style is similar to +the \glostyle{tree} style except that each group has a heading. + +\item[treehypergroup] The \glostyle{treehypergroup} style is like +\glostyle{treegroup} but has a set of links to the glossary +groups. The navigation line is the same as that for +\glostyle{listhypergroup}, described above, but is formatted using +\cs{glstreenavigationfmt}. + +\item[treenoname] The \glostyle{treenoname} style is like +the \glostyle{tree} style except that the name for each sub-entry +is ignored. + +\item[treenonamegroup] The \glostyle{treenonamegroup} style is +similar to the \glostyle{treenoname} style except that each group +has a heading. + +\item[treenonamehypergroup] The \glostyle{treenonamehypergroup} +style is like \glostyle{treenonamegroup} but has a set of links to +the glossary groups. The navigation line is the same as that for +\glostyle{listhypergroup}, described above, but is formatted using +\cs{glstreenavigationfmt}. + +\item[alttree] The \glostyle{alttree} style is similar to the +\glostyle{tree} style except that the indentation for each level +is determined by the width of the text specified by +\begin{definition}[\DescribeMacro{\glssetwidest}] +\cs{glssetwidest}\oarg{level}\marg{text} +\end{definition} +The optional argument \meta{level} indicates the level, where +0 indicates the top-most level, 1 indicates the first level +sub-entries, etc. If \cs{glssetwidest} hasn't been used for a +given sub-level, the level~0 widest text is used instead. If +\meta{level} is omitted, 0 is assumed. + +As from v4.22, the \sty{glossary-tree} package also provides +\begin{definition}[\DescribeMacro\glsfindwidesttoplevelname] +\cs{glsfindwidesttoplevelname}\oarg{glossary list} +\end{definition} +This iterates over all parentless entries in the given glossary +lists and determines the widest entry. If the optional argument is +omitted, all glossaries are assumed (as per \cs{forallglossaries}). + +For example, to have the same name width for all glossaries: +\begin{verbatim} +\glsfindwidesttoplevelname +\setglossarystyle{alttree} +\printglossaries +\end{verbatim} +Alternatively, to compute the widest entry for each glossary +before it's displayed: +\begin{verbatim} +\renewcommand{\glossarypreamble}{% + \glsfindwidesttoplevelname[\currentglossary]} +\setglossarystyle{alttree} +\printglossaries +\end{verbatim} + +\begin{important} +These commands only affects the \glostyle{alttree} styles, including those +listed below and the ones in the \sty{glossary-mcols} package. +If you forget to set the widest entry name, the description will +overwrite the name. +\end{important} + +For each level, the name is placed to the left of the paragraph +block containing the symbol (optional) and the description. If the +symbol is present, it is placed in parentheses before the +description. + +The name is placed inside a left-aligned \cs{makebox}. As from +v4.19, this can now be adjusted by redefining +\begin{definition}[\DescribeMacro\glstreenamebox] +\cs{glstreenamebox}\marg{width}\marg{text} +\end{definition} +where \meta{width} is the width of the box and \meta{text} is the +contents of the box. For example, to make the name right-aligned: +\begin{verbatim} +\renewcommand*{\glstreenamebox}[2]{% + \makebox[#1][r]{#2}% +} +\end{verbatim} + +\item[alttreegroup] The \glostyle{alttreegroup} is like the +\glostyle{alttree} style except that each group has a heading. + +\item[alttreehypergroup] The \glostyle{alttreehypergroup} style is +like \glostyle{alttreegroup} but has a set of links to the glossary +groups. The navigation line is the same as that for +\glostyle{listhypergroup}, described above. + +\end{description} + +\subsection{Multicols Style} +\label{sec:mcolstyles} + +The \sty{glossary-mcols} package provides tree-like styles that are +in the \env{multicols} environment (defined by the \sty{multicol} +package). The style names are as their analogous tree styles (as +defined in \sectionref{sec:treestyles}) but are prefixed with +\qt{mcol}. +For example, the \glostyle{mcolindex} style is essentially the +\glostyle{index} style but put in a \env{multicols} environment. +For the complete list, see \tableref{tab:mcols}. The +\sty{glossary-tree} package is automatically loaded by +\sty{glossary-mcols} (even if the \pkgopt{notree} package option is +used when loading \styfmt{glossaries}). The formatting commands +\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and +\cs{glstreenavigationfmt} are all used by the corresponding +\sty{glossary-mcols} styles. + +\begin{important} +Note that \sty{glossary-mcols} is not loaded by \styfmt{glossaries}. If +you want to use any of the multicol styles in that package you need +to load it explicitly with \cs{usepackage} and set the required glossary +style using \ics{setglossarystyle}. +\end{important} + +The default number of columns is 2, but can be changed by redefining +\begin{definition}[\DescribeMacro{\glsmcols}] +\cs{glsmcols} +\end{definition} +to the required number. For example, for a three column glossary: +\begin{verbatim} +\usepackage{glossary-mcols} +\renewcommand*{\glsmcols}{3} +\setglossarystyle{mcolindex} +\end{verbatim} + +\begin{table}[htbp] +\caption{Multicolumn Styles} +\label{tab:mcols} +\centering +\begin{tabular}{ll} +\bfseries +\sty{glossary-mcols} Style & +\bfseries +Analogous Tree Style\\ +\glostyle{mcolindex} & \glostyle{index}\\ +\glostyle{mcolindexgroup} & \glostyle{indexgroup}\\ +\glostyle{mcolindexhypergroup} or \glostyle{mcolindexspannav} & \glostyle{indexhypergroup}\\ +\glostyle{mcoltree} & \glostyle{tree}\\ +\glostyle{mcoltreegroup} & \glostyle{treegroup}\\ +\glostyle{mcoltreehypergroup} or \glostyle{mcoltreespannav} & \glostyle{treehypergroup}\\ +\glostyle{mcoltreenoname} & \glostyle{treenoname}\\ +\glostyle{mcoltreenonamegroup} & \glostyle{treenonamegroup}\\ +\glostyle{mcoltreenonamehypergroup} or +\glostyle{mcoltreenonamespannav} & \glostyle{treenonamehypergroup}\\ +\glostyle{mcolalttree} & \glostyle{alttree}\\ +\glostyle{mcolalttreegroup} & \glostyle{alttreegroup}\\ +\glostyle{mcolalttreehypergroup} or \glostyle{mcolalttreespannav} & \glostyle{alttreehypergroup} +\end{tabular} +\end{table} + +The styles with a navigation line, such as +\glostyle{mcoltreehypergroup}, now have a variant (as from v4.22) +with \qt{hypergroup} replaced with \qt{spannav} in the style name. +The original \qt{hypergroup} styles place the navigation line at the +start of the first column. The newer \qt{spannav} styles put the +navigation line in the optional argument of the \env{multicols} +environment so that it spans across all the columns. + +\subsection{In-Line Style} +\label{sec:inline} + +This section covers the \sty{glossary-inline} package that supplies +the \glostyle{inline} style. This is a style that is designed for +in-line use (as opposed to block styles, such as lists or tables). +This style doesn't display the \gls{numberlist}. + +You will most likely need to redefine \ics{glossarysection} with +this style. For example, suppose you are required to have your +glossaries and list of acronyms in a footnote, you can do: +\begin{verbatim} + \usepackage{glossary-inline} + + \renewcommand*{\glossarysection}[2][]{\textbf{#1}: } + \setglossarystyle{inline} +\end{verbatim} + +\begin{important} +Note that you need to include \sty{glossary-inline} with +\cs{usepackage} as it's not automatically included by the +\styfmt{glossaries} package and then set the style using +\ics{setglossarystyle}. +\end{important} + +Where you need to include your glossaries as a footnote you can do: +\begin{verbatim} +\footnote{\printglossaries} +\end{verbatim} + +The \glostyle{inline} style is governed by the following: +\begin{definition}[\DescribeMacro{\glsinlineseparator}] +\ics{glsinlineseparator} +\end{definition} +This defaults to \qt{\texttt{\glsinlineseparator}} and is used between +main (i.e.\ level~0) entries. +\begin{definition}[\DescribeMacro{\glsinlinesubseparator}] +\ics{glsinlinesubseparator} +\end{definition} +This defaults to \qt{\texttt{\glsinlinesubseparator}} and is used between +sub-entries. +\begin{definition}[\DescribeMacro{\glsinlineparentchildseparator}] +\ics{glsinlineparentchildseparator} +\end{definition} +This defaults to \qt{\texttt{\glsinlineparentchildseparator}} and is used between +a parent main entry and its first sub-entry. +\begin{definition}[\DescribeMacro{\glspostinline}] +\ics{glspostinline} +\end{definition} +This defaults to \qt{\texttt{\glsinlineseparator}} and is used at the end +of the glossary. +\begin{definition}[\DescribeMacro\glsinlinenameformat] +\cs{glsinlinenameformat}\marg{label}\marg{name} +\end{definition} +This is used to format the entry name and defaults to +\cs{glstarget}\marg{label}\marg{name}, where \meta{name} is provided +in the form \cs{glossentryname}\marg{label} and \meta{label} is the +entry's label. For example, if you want the name to appear in +smallcaps: +\begin{verbatim} +\renewcommand*{\glsinlinenameformat}[2]{\glstarget{#1}{\textsc{#2}}} +\end{verbatim} +Sub-entry names are formatted according to +\begin{definition}[\DescribeMacro\glsinlinesubnameformat] +\cs{glsinlinesubnameformat}\marg{label}\marg{name} +\end{definition} +This defaults to \cs{glstarget}\marg{label}\verb|{}| so the +sub-entry name is ignored. + +If the description has been suppressed (according to +\cs{ifglsdescsuppressed}) then +\begin{definition}[\DescribeMacro\glsinlineemptydescformat] +\cs{glsinlineemptydescformat}\marg{symbol}\marg{number list} +\end{definition} +(which defaults to nothing) is used, +otherwise the description is formatted according to +\begin{definition}[\DescribeMacro\glsinlinedescformat] +\cs{glsinlinedescformat}\marg{description}\marg{symbol}\marg{number +list} +\end{definition} +This defaults to just \cs{space}\meta{description} so the symbol and +location list are ignored. If the description is missing (according +to \cs{ifglshasdesc}), then \cs{glsinlineemptydescformat} is used +instead. + +For example, if you want a colon between the name and the +description: +\begin{verbatim} +\renewcommand*{\glsinlinedescformat}[3]{: #1} +\end{verbatim} + +The sub-entry description is formatted according to: +\begin{definition}[\DescribeMacro\glsinlinesubdescformat] +\cs{glsinlinesubdescformat}\marg{description}\marg{symbol}\marg{number +list} +\end{definition} +This defaults to just \meta{description}. + +\section{Defining your own glossary style} +\label{sec:newglossarystyle} + +If the predefined styles don't fit your requirements, you can +define your own style using: +\begin{definition}[\DescribeMacro{\newglossarystyle}] +\cs{newglossarystyle}\marg{name}\marg{definitions} +\end{definition} +where \meta{name} is the name of the new glossary style (to be +used in \cs{setglossarystyle}). The second argument \meta{definitions} +needs to redefine all of the following: + +\begin{definition}[\DescribeEnv{theglossary}] +\env{theglossary} +\end{definition} +This environment defines how the main body of the glossary should +be typeset. Note that this does not include the section heading, +the glossary preamble (defined by \ics{glossarypreamble}) or the +glossary postamble (defined by \ics{glossarypostamble}). For example, +the \glostyle{list} style uses the \env{description} environment, +so the \env{theglossary} environment is simply redefined to begin +and end the \env{description} environment. + +\begin{definition}[\DescribeMacro{\glossaryheader}] +\cs{glossaryheader} +\end{definition} +This macro indicates what to do at the start of the main body +of the glossary. Note that this is not the same as +\ics{glossarypreamble}, which should not be affected by changes in +the glossary style. The \glostyle{list} glossary style redefines +\ics{glossaryheader} to do nothing, whereas the \glostyle{longheader} +glossary style redefines \cs{glossaryheader} to do a header row. + +\begin{definition}[\DescribeMacro{\glsgroupheading}] +\cs{glsgroupheading}\marg{label} +\end{definition} +This macro indicates +what to do at the start of each logical block within the main body +of the glossary. If you use \gls{makeindex} the glossary is +sub-divided into a maximum of twenty-eight logical blocks that are +determined by the first character of the \gloskey{sort} key (or +\gloskey{name} key if the \gloskey{sort} key is omitted). The +sub-divisions are in the following order: symbols, numbers, A, +\ldots, Z\@. If you use \gls{xindy}, the sub-divisions depend on +the language settings. + +Note that the argument to \cs{glsgroupheading} +is a label \emph{not} the group title. The group title can be obtained +via +\begin{definition}[\DescribeMacro{\glsgetgrouptitle}] +\cs{glsgetgrouptitle}\marg{label} +\end{definition} +This obtains the title as follows: if \meta{label} consists of a +single non-active character or \meta{label} is equal to +\texttt{glssymbols} or \texttt{glsnumbers} and +\cs{}\meta{label}\texttt{groupname} exists, this is taken to be the +title, otherwise the title is just \meta{label}. (The \qt{symbols} +group has the label \texttt{glssymbols}, so the command +\ics{glssymbolsgroupname} is used, and the \qt{numbers} group has the +label \texttt{glsnumbers}, so the command \ics{glsnumbersgrouptitle} +is used.) If you are using \gls{xindy}, \meta{label} may be an +active character (for example \o), in which case the title will be +set to just \meta{label}. You can redefine \cs{glsgetgrouptitle} if +this is unsuitable for your document. + +A navigation hypertarget can be created using +\begin{definition}[\DescribeMacro{\glsnavhypertarget}] +\cs{glsnavhypertarget}\marg{label}\marg{text} +\end{definition} +This typically requires \cs{glossaryheader} to be redefined to use +\begin{definition}[\DescribeMacro\glsnavigation] +\cs{glsnavigation} +\end{definition} +which displays the navigation line. + +For further details about \cs{glsnavhypertarget}, see +\ifpdf section~\ref*{sec:code:hypernav} in \fi the documented code +(\texttt{glossaries-code.pdf}). + +Most of the predefined glossary styles redefine \cs{glsgroupheading} +to simply ignore its argument. The \glostyle{listhypergroup} style +redefines \cs{glsgroupheading} as follows: +\begin{verbatim} +\renewcommand*{\glsgroupheading}[1]{% +\item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]} +\end{verbatim} +See also \cs{glsgroupskip} below. (Note that command definitions within +\ics{newglossarystyle} must use \verb|##1| instead of \verb|#1| etc.) + +\begin{definition}[\DescribeMacro{\glsgroupskip}] +\cs{glsgroupskip} +\end{definition} +This macro determines what to do after one logical group but before +the header for the next logical group. The \glostyle{list} glossary +style simply redefines \cs{glsgroupskip} to be \ics{indexspace}, +whereas the tabular-like styles redefine \cs{glsgroupskip} to +produce a blank row. + +As from version 3.03, the package option \pkgopt{nogroupskip} can be +used to suppress this default gap for the predefined styles. + +\begin{definition}[\DescribeMacro{\glossentry}] +\cs{glossentry}\marg{label}\marg{number list} +\end{definition} +This macro indicates what to do for each top-level (level~0) glossary entry. +The entry label is given by \meta{label} and the associated +\gls{numberlist} is given by \meta{number list}. You can redefine +\ics{glossentry} to use commands like \ics{glossentryname}\marg{label}, +\ics{glossentrydesc}\marg{label} and \ics{glossentrysymbol}\marg{label} +to display the name, description and symbol fields, or to access +other fields, use commands like \ics{glsentryuseri}\marg{label}. +(See \sectionref{sec:glsnolink} for further details.) You can also +use the following commands: + +\begin{definition}[\DescribeMacro{\glsentryitem}] +\cs{glsentryitem}\marg{label} +\end{definition} +This macro will increment and display the associated counter for the +main (level~0) entries if the \pkgopt{entrycounter} or +\pkgopt{counterwithin} package options have been used. This macro +is typically called by \cs{glossentry} before \cs{glstarget}. +The format of the counter is controlled by the macro +\begin{definition}[\DescribeMacro{\glsentrycounterlabel}] +\cs{glsentrycounterlabel} +\end{definition} + +Each time you use a glossary entry it creates a hyperlink (if +hyperlinks are enabled) to the relevant line in the glossary. +Your new glossary style must therefore redefine +\cs{glossentry} to set the appropriate target. This +is done using +\begin{definition}[\DescribeMacro{\glstarget}] +\cs{glstarget}\marg{label}\marg{text} +\end{definition} +where \meta{label} is the entry's label. Note that you +don't need to worry about whether the \sty{hyperref} package has +been loaded, as \cs{glstarget} won't create a target if +\cs{hypertarget} hasn't been defined. + +For example, the \glostyle{list} style defines \cs{glossentry} as follows: +\begin{verbatim} + \renewcommand*{\glossentry}[2]{% + \item[\glsentryitem{##1}% + \glstarget{##1}{\glossentryname{##1}}] + \glossentrydesc{##1}\glspostdescription\space ##2} +\end{verbatim} + +Note also that \meta{number list} will always be of the form +\begin{definition} +\ics{glossaryentrynumbers}\{\cs{relax}\\ +\ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}\} +\end{definition} +where \meta{number(s)} +may contain \ics{delimN} (to delimit individual numbers) and/or +\ics{delimR} (to indicate a range of numbers). There may be +multiple occurrences of +\ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}, but note +that the entire number list is enclosed within the argument +of \ics{glossaryentrynumbers}. The user can redefine this to change +the way the entire number list is formatted, regardless of +the glossary style. However the most common use of +\ics{glossaryentrynumbers} is to provide a means of suppressing the +number list altogether. (In fact, the \pkgopt{nonumberlist} option +redefines \ics{glossaryentrynumbers} to ignore its argument.) +Therefore, when you define a new glossary style, you don't need +to worry about whether the user has specified the +\pkgopt{nonumberlist} package option. + +\begin{definition}[\DescribeMacro{\subglossentry}] +\cs{subglossentry}\marg{level}\marg{label}\marg{number list} +\end{definition} +This is used to display sub-entries. +The first argument, \meta{level}, indicates the sub-entry level. +This must be an integer from 1 (first sub-level) onwards. The +remaining arguments are analogous to those for +\ics{glossentry} described above. + +\begin{definition}[\DescribeMacro{\glssubentryitem}] +\cs{glssubentryitem}\marg{label} +\end{definition} +This macro will increment and display the associated counter for the +level~1 entries if the \pkgopt{subentrycounter} package option has +been used. This macro is typically called by \cs{subglossentry} +before \ics{glstarget}. The format of the counter is controlled by +the macro +\begin{definition}[\DescribeMacro{\glssubentrycounterlabel}] +\cs{glssubentrycounterlabel} +\end{definition} + +Note that \ics{printglossary} (which \ics{printglossaries} calls) +sets +\begin{definition}[\DescribeMacro{\currentglossary}] +\cs{currentglossary} +\end{definition} +to the current glossary label, so it's possible to create a glossary +style that varies according to the glossary type. + +For further details of these commands, see \ifpdf +section~\ref*{sec:code:printglos} \fi \qt{Displaying the glossary} +in the documented code (\texttt{glossaries-code.pdf}). + +\begin{example}{Creating a completely new style}{sec:exnewstyle} + +If you want a completely new style, you will need to redefine all +of the commands and the environment listed above. + +For example, suppose you want each entry to start with a bullet point. +This means that the glossary should be placed in the \env{itemize} +environment, so \env{theglossary} should start and end that +environment. Let's also suppose that you don't want anything between +the glossary groups (so \ics{glsgroupheading} and \ics{glsgroupskip} +should do nothing) and suppose you don't want anything to appear +immediately after \verb|\begin{theglossary}| (so \ics{glossaryheader} +should do nothing). In addition, let's suppose the symbol should +appear in brackets after the name, followed by the description and +last of all the \gls{numberlist} should appear within square brackets +at the end. Then you can create this new glossary style, called, say, +\texttt{mylist}, as follows: +\begin{verbatim} + \newglossarystyle{mylist}{% + % put the glossary in the itemize environment: + \renewenvironment{theglossary}% + {\begin{itemize}}{\end{itemize}}% + % have nothing after \begin{theglossary}: + \renewcommand*{\glossaryheader}{}% + % have nothing between glossary groups: + \renewcommand*{\glsgroupheading}[1]{}% + \renewcommand*{\glsgroupskip}{}% + % set how each entry should appear: + \renewcommand*{\glossentry}[2]{% + \item % bullet point + \glstarget{##1}{\glossentryname{##1}}% the entry name + \space (\glossentrysymbol{##1})% the symbol in brackets + \space \glossentrydesc{##1}% the description + \space [##2]% the number list in square brackets + }% + % set how sub-entries appear: + \renewcommand*{\subglossentry}[3]{% + \glossentry{##2}{##3}}% + } +\end{verbatim} +Note that this style creates a flat glossary, where sub-entries +are displayed in exactly the same way as the top level entries. +It also hasn't used \ics{glsentryitem} or \ics{glssubentryitem} so +it won't be affected by the \pkgopt{entrycounter}, +\pkgopt{counterwithin} or \pkgopt{subentrycounter} package options. + +Variations: +\begin{itemize} +\item You might want the entry name to be capitalised, in +which case use \ics{Glossentryname} instead of \ics{glossentryname}. + +\item You might want to check if the symbol hasn't been set and omit +the parentheses if the symbol is absent. In this case you can use +\ics{ifglshassymbol} (see \sectionref{sec:utilities}): +\begin{verbatim} + \renewcommand*{\glossentry}[2]{% + \item % bullet point + \glstarget{##1}{\glossentryname{##1}}% the entry name + \ifglshassymbol{##1}% check if symbol exists + {% + \space (\glossentrysymbol{##1})% the symbol in brackets + }% + {}% no symbol so do nothing + \space \glossentrydesc{##1}% the description + \space [##2]% the number list in square brackets + }% +\end{verbatim} +\end{itemize} +\end{example} + +\begin{example}{Creating a new glossary style based on an +existing style}{sec:exadaptstyle} + +If you want to define a new style that is a slightly modified +version of an existing style, you can use \ics{setglossarystyle} +within the second argument of \ics{newglossarystyle} followed by +whatever alterations you require. For example, suppose you want +a style like the \glostyle{list} style but you don't want the extra +vertical space created by \ics{indexspace} between groups, then you +can create a new glossary style called, say, \texttt{mylist} as +follows: +\begin{verbatim} +\newglossarystyle{mylist}{% +\setglossarystyle{list}% base this style on the list style +\renewcommand{\glsgroupskip}{}% make nothing happen + % between groups +} +\end{verbatim} +(In this case, you can actually achieve the same effect using the +\glostyle{list} style in combination with the package option +\pkgopt{nogroupskip}.) +\end{example} + +\begin{example}{Example: creating a glossary style that uses the +\texorpdfstring{\gloskey{user1}}{user1}, \ldots, +\texorpdfstring{\gloskey{user6}}{user6} keys}{sec:exuserstyle} + +Suppose each entry not only has an associated symbol, +but also units (stored in \gloskey{user1}) and dimension +(stored in \gloskey{user2}). Then you can define a glossary style +that displays each entry in a \env{longtable} as follows: +\begin{verbatim} +\newglossarystyle{long6col}{% + % put the glossary in a longtable environment: + \renewenvironment{theglossary}% + {\begin{longtable}{lp{\glsdescwidth}cccp{\glspagelistwidth}}}% + {\end{longtable}}% + % Set the table's header: + \renewcommand*{\glossaryheader}{% + \bfseries Term & \bfseries Description & \bfseries Symbol & + \bfseries Units & \bfseries Dimensions & \bfseries Page List + \\\endhead}% + % No heading between groups: + \renewcommand*{\glsgroupheading}[1]{}% + % Main (level 0) entries displayed in a row optionally numbered: + \renewcommand*{\glossentry}[2]{% + \glsentryitem{##1}% Entry number if required + \glstarget{##1}{\glossentryname{##1}}% Name + & \glossentrydesc{##1}% Description + & \glossentrysymbol{##1}% Symbol + & \glsentryuseri{##1}% Units + & \glsentryuserii{##1}% Dimensions + & ##2% Page list + \tabularnewline % end of row + }% + % Similarly for sub-entries (no sub-entry numbers): + \renewcommand*{\subglossentry}[3]{% + % ignoring first argument (sub-level) + \glstarget{##2}{\glossentryname{##2}}% Name + & \glossentrydesc{##2}% Description + & \glossentrysymbol{##2}% Symbol + & \glsentryuseri{##2}% Units + & \glsentryuserii{##2}% Dimensions + & ##3% Page list + \tabularnewline % end of row + }% + % Nothing between groups: + \renewcommand*{\glsgroupskip}{}% +} +\end{verbatim} +\end{example} + +\chapter{Utilities} +\label{sec:utilities} + +This section describes some utility commands. Additional commands +can be found in the documented code (glossaries-code.pdf). + +\section{Loops} +\label{sec:loops} + +\begin{important} +Some of the commands described here take a comma-separated list as +an argument. As with \LaTeX's \cs{@for} command, make sure your list +doesn't have any unwanted spaces in it as they don't get stripped. +(Discussed in more detail in +\href{http://www.dickimaw-books.com/latex/admin/html/docsvlist.shtml#spacesinlists}{\S2.7.2 of \qt{\LaTeX\ for Administrative +Work}}.) +\end{important} + +\begin{definition}[\DescribeMacro{\forallglossaries}] +\cs{forallglossaries}\oarg{glossary list}\marg{cs}\marg{body} +\end{definition} +This iterates through \meta{glossary list}, a comma-separated list +of glossary labels (as supplied when the glossary was defined). +At each iteration \meta{cs} (which must be a control sequence) is +set to the glossary label for the current iteration and \meta{body} +is performed. If \meta{glossary list} is omitted, the default is to +iterate over all glossaries (except the ignored ones). + +\begin{definition}[\DescribeMacro{\forallacronyms}] +\cs{forallacronyms}\marg{cs}\marg{body} +\end{definition} +This is like \cs{forallglossaries} but only iterates over the +lists of acronyms (that have previously been declared using +\ics{DeclareAcronymList} or the \pkgopt{acronymlists} package +option). This command doesn't have an optional argument. If you want +to explicitly say which lists to iterate over, just use the optional +argument of \cs{forallglossaries}. + +\begin{definition}[\DescribeMacro{\forglsentries}] +\cs{forglsentries}\oarg{glossary label}\marg{cs}\marg{body} +\end{definition} +This iterates through all entries in the glossary given by +\meta{glossary label}. At each iteration \meta{cs} (which must be a +control sequence) is set to the entry label for the current +iteration and \meta{body} is performed. If \meta{glossary label} is +omitted, \ics{glsdefaulttype} (usually the main glossary) is used. + +\begin{definition}[\DescribeMacro{\forallglsentries}] +\cs{forallglsentries}\oarg{glossary list}\marg{cs}\marg{body} +\end{definition} +This is like \cs{forglsentries} but for each glossary in +\meta{glossary list} (a comma-separated list of glossary labels). If +\meta{glossary list} is omitted, the default is the list of all +defined glossaries (except the ignored ones). At each iteration +\meta{cs} is set to the entry label and \meta{body} is performed. +(The current glossary label can be obtained using +\cs{glsentrytype}\marg{cs} within \meta{body}.) + +\section{Conditionals} +\label{sec:conditionals} + +\begin{definition}[\DescribeMacro{\ifglossaryexists}] +\cs{ifglossaryexists}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary given by \meta{label} exists. If it +does \meta{true part} is performed, otherwise \meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglsentryexists}] +\cs{ifglsentryexists}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary entry given by \meta{label} exists. If it +does \meta{true part} is performed, otherwise \meta{false part}. +(Note that \cs{ifglsentryexists} will always be true after the +containing glossary has been displayed via \ics{printglossary} +or \ics{printglossaries} even if the entry is explicitly defined +later in the document. This is because the entry has to be defined +before it can be displayed in the glossary, see \sectionref{sec:techissues} for +further details.) + +\begin{definition}[\DescribeMacro{\glsdoifexists}] +\cs{glsdoifexists}\marg{label}\marg{code} +\end{definition} +Does \meta{code} if the entry given by \meta{label} exists. If it +doesn't exist, an error is generated. (This command uses +\cs{ifglsentryexists}.) + +\begin{definition}[\DescribeMacro{\glsdoifnoexists}] +\cs{glsdoifnoexists}\marg{label}\marg{code} +\end{definition} +Does the reverse of \cs{glsdoifexists}. (This command uses +\cs{ifglsentryexists}.) + +\begin{definition}[\DescribeMacro{\glsdoifexistsorwarn}] +\cs{glsdoifexistsorwarn}\marg{label}\marg{code} +\end{definition} +As \cs{glsdoifexists} but issues a warning rather than an error if +the entry doesn't exist. + +\begin{definition}[\DescribeMacro{\glsdoifexistsordo}] +\cs{glsdoifexistsordo}\marg{label}\marg{code}\marg{else code} +\end{definition} +Does \meta{code} if the entry given by \meta{label} exists otherwise +generate an error and do \meta{else code}. + +\begin{definition}[\DescribeMacro{\glsdoifnoexistsordo}] +\cs{glsdoifnoexistsordo}\marg{label}\marg{code}\marg{else code} +\end{definition} +Does \meta{code} if the entry given by \meta{label} doesn't exist otherwise +generate an error and do \meta{else code}. + +\begin{definition}[\DescribeMacro{\ifglsused}] +\cs{ifglsused}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +See \sectionref{sec:glsunset}. + +\begin{definition}[\DescribeMacro{\ifglshaschildren}] +\cs{ifglshaschildren}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary entry given by \meta{label} has any +sub-entries. If it does, \meta{true part} is performed, otherwise +\meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglshasparent}] +\cs{ifglshasparent}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary entry given by \meta{label} has a parent +entry. If it does, \meta{true part} is performed, otherwise +\meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglshassymbol}] +\cs{ifglshassymbol}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the glossary entry given by \meta{label} has had the +\gloskey{symbol} field set. If it has, \meta{true part} is performed, +otherwise \meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglshaslong}] +\cs{ifglshaslong}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the glossary entry given by \meta{label} has had the +\gloskey{long} field set. If it has, \meta{true part} is performed, +otherwise \meta{false part}. This should be true for any entry that +has been defined via \ics{newacronym}. +There is no check for the existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\ifglshasshort}] +\cs{ifglshasshort}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the glossary entry given by \meta{label} has had the +\gloskey{short} field set. If it has, \meta{true part} is performed, +otherwise \meta{false part}. This should be true for any entry that +has been defined via \ics{newacronym}. +There is no check for the existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\ifglshasdesc}] +\cs{ifglshasdesc}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the \gloskey{description} field is non-empty for +the entry given by \meta{label}. If it has, \meta{true part} is +performed, otherwise \meta{false part}. Compare with: +\begin{definition}[\DescribeMacro{\ifglsdescsuppressed}] +\cs{ifglsdescsuppressed}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the \gloskey{description} field has been set to just +\ics{nopostdesc} for the entry given by \meta{label}. If it has, +\meta{true part} is performed, otherwise \meta{false part}. +There is no check for the existence of \meta{label}. + +For all other fields you can use: +\begin{definition}[\DescribeMacro\ifglshasfield] +\cs{ifglshasfield}\marg{field}\marg{label}\marg{true part}\marg{false +part} +\end{definition} +This tests the value of the field given by \meta{field} for the entry +identified by \meta{label}. If the value is empty \emph{or the default +value}, then \meta{false part} is performed, otherwise \meta{true +part} is performed. If the field supplied is unrecognised \meta{false part} +is performed and a warning is issued. Unlike the above commands, +such as \cs{ifglshasshort}, an error occurs if the entry is +undefined. + +As from version 4.23, within \meta{true part} you can use +\begin{definition}[\DescribeMacro\glscurrentfieldvalue] +\cs{glscurrentfieldvalue} +\end{definition} +to access the field value. This command is +initially defined to nothing but has +no relevance outside \meta{true part}. This saves re-accessing the +field if the test is true. For example: +\begin{verbatim} +\ifglshasfield{useri}{sample}{, \glscurrentfieldvalue}{} +\end{verbatim} +will insert a comma, space and the field value if the +\gloskey{user1} key has been set for +the entry whose label is \texttt{sample}. + +You can test if the value of the field is equal to a given string +using: +\begin{definition}[\DescribeMacro\ifglsfieldeq] +\cs{ifglsfieldeq}\marg{label}\marg{field}\marg{string}\marg{true}\marg{false} +\end{definition} +In this case the \meta{field} must be the field name not the key +(see \tableref{tab:fieldmap}). If the field isn't recognised, an +error will occur. This command internally uses +\sty{etoolbox}'s \cs{ifcsstring} to perform the comparison. \emph{The +string is not expanded during the test.} + +The result may vary depending on whether or not expansion is on for +the given field (when the entry was defined). For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +This will produce \qt{TRUE} in both cases since expansion is on, so +\cs{foo} was expanded to \qt{FOO} when \texttt{sample2} was defined. +If the tests are changed to: +\begin{verbatim} +\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +\end{verbatim} +then this will produce \qt{FALSE} in both cases. Now suppose +expansion is switched off for the \gloskey{user1} key: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\glssetnoexpandfield{useri} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +This now produces \qt{TRUE} for the first case (comparing \qt{FOO} +with \qt{FOO}) and \qt{FALSE} for the second case (comparing +\qt{\cs{foo}} with \qt{FOO}). + +The reverse happens in the following: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\glssetnoexpandfield{useri} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +This now produces \qt{FALSE} for the first case (comparing \qt{FOO} +with \qt{\cs{foo}}) and \qt{TRUE} for the second case (comparing +\qt{\cs{foo}} with \qt{\cs{foo}}). + +You can test if the value of a field is equal to the replacement +text of a command using: +\begin{definition}[\DescribeMacro\ifglsfielddefeq] +\cs{ifglsfielddefeq}\marg{label}\marg{field}\marg{command}\marg{true}\marg{false} +\end{definition} +This internally uses \sty{etoolbox}'s \cs{ifdefstrequal} command to +perform the comparison. The argument \meta{command} must be a macro. + +For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\glssetnoexpandfield{useri} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfielddefeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + +\ifglsfielddefeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +Here, the first case produces \qt{TRUE} since the value of the +\texttt{useri} field (\qt{FOO}) is the same as the replacement text +(definition) of \cs{foo} (\qt{FOO}). We have the result +\qt{\texttt{FOO}} is equal to \qt{\texttt{FOO}}. + +The second case produces \qt{FALSE} since the value of the +\texttt{useri} field (\qt{\cs{foo}}) is not the same as the replacement +text (definition) of \cs{foo} (\qt{FOO}). No expansion has been +performed on the value of the \texttt{useri} field. We have the +result \qt{\cs{foo}} is not equal to \qt{\texttt{FOO}}. + +If we add: +\begin{verbatim} +\newcommand{\FOO}{\foo} +\ifglsfielddefeq{sample2}{useri}{\FOO}{TRUE}{FALSE}. +\end{verbatim} +we now get \qt{TRUE} since the value of the +\texttt{useri} field (\qt{\cs{foo}}) is the same as the replacement +text (definition) of \cs{FOO} (\qt{\cs{foo}}). We have the result \qt{\cs{foo}} +is equal to \qt{\cs{foo}}. + +There is a similar command that requires the control sequence name +(without the leading backslash) instead of the actual control sequence: +\begin{definition}[\DescribeMacro\ifglsfieldcseq] +\cs{ifglsfieldcseq}\marg{label}\marg{field}\marg{csname}\marg{true}\marg{false} +\end{definition} +This internally uses \sty{etoolbox}'s \cs{ifcsstrequal} command +instead of \cs{ifdefstrequal}. + +\section{Fetching and Updating the Value of a Field} +\label{sec:fetchset} + +You can fetch the value of a given field and store it in a control +sequence using: +\begin{definition}[\DescribeMacro\glsfieldfetch] +\cs{glsfieldfetch}\marg{label}\marg{field}\marg{cs} +\end{definition} +where \meta{label} is the label identifying the glossary entry, +\meta{field} is the field label (see \tableref{tab:fieldmap}) +and \meta{cs} is the control sequence in which to store the value. +Remember that \meta{field} is the internal label and is not +necessarily the same as the key used to set that field in the +argument of \cs{newglossaryentry} (or the optional argument of +\cs{newacronym}). + +You can change the value of a given field using one of the following +commands. Note that these commands only change the value of the +given field. They have no affect on any related field. For example, +if you change the value of the \gloskey{text} field, it won't modify the +value given by the \gloskey{name}, \gloskey{plural}, \gloskey{first} or any other related key. + +In all the four related commands below, \meta{label} and +\meta{field} are as above and \meta{definition} is the new value +of the field. + +\begin{definition}[\DescribeMacro\glsfielddef] +\cs{glsfielddef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{def} to change the value of the field (so it will be +localised by any grouping). + +\begin{definition}[\DescribeMacro\glsfieldedef] +\cs{glsfieldedef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{edef} to change the value of the field (so it will be +localised by any grouping). Any fragile commands contained in the +\meta{definition} must be protected. + +\begin{definition}[\DescribeMacro\glsfieldgdef] +\cs{glsfieldgdef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{gdef} to change the value of the field. + +\begin{definition}[\DescribeMacro\glsfieldxdef] +\cs{glsfieldxdef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{xdef} to change the value of the field. Any fragile +commands contained in the \meta{definition} must be protected. + + +\chapter{Prefixes or Determiners}\label{sec:prefix} + +The \sty{glossaries-prefix} package that comes with the +\styfmt{glossaries} package provides +additional keys that can be used as prefixes. For example, if you +want to specify determiners (such +as \qt{a}, \qt{an} or \qt{the}). The \styfmt{glossaries-prefix} +package automatically loads the \styfmt{glossaries} package and has +the same package options. + +The extra keys for \ics{newglossaryentry} are as follows: +\begin{description} +\item[\gloskey{prefix}] The prefix associated with the +\gloskey{text} key. This defaults to nothing. + +\item[\gloskey{prefixplural}] The prefix associated with the +\gloskey{plural} key. This defaults to nothing. + +\item[\gloskey{prefixfirst}] The prefix associated with the +\gloskey{first} key. If omitted, this defaults to the value of the +\gloskey{prefix} key. + +\item[\gloskey{prefixfirstplural}] The prefix associated with the +\gloskey{firstplural} key. If omitted, this defaults to the value of +the \gloskey{prefixplural} key. +\end{description} + +\begin{example}{Defining Determiners}{ex:determiners} +Here's the start of my example document: +\begin{verbatim} +documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage[toc,acronym]{glossaries-prefix} +\end{verbatim} +Note that I've simply replaced \styfmt{glossaries} from previous +sample documents with \styfmt{glossaries-prefix}. Now for a sample +definition\footnote{Single letter words, such as \qt{a} and \qt{I} +should typically not appear at the end of a line, hence the +non-breakable space after \qt{a} in the \gloskey{prefix} field.}: +\begin{verbatim} +\newglossaryentry{sample}{name={sample},% + description={an example},% + prefix={a~},% + prefixplural={the\space}% +} +\end{verbatim} +Note that I've had to explicitly insert a~space after the prefix. +This allows for the possibility of prefixes that shouldn't have a~space, +such as: +\begin{verbatim} +\newglossaryentry{oeil}{name={oeil}, + plural={yeux}, + description={eye}, + prefix={l'}, + prefixplural={les\space}} +\end{verbatim} +Where a space is required at the end of the prefix, you must use +a~spacing command, such as \cs{space}, \verb*|\ | (backslash space) or +\verb|~| due to the automatic spacing trimming performed in +\meta{key}=\meta{value} options. + +The prefixes can also be used with acronyms. For example: +\begin{verbatim} +\newacronym + [% + prefix={an\space},prefixfirst={a~}% + ]{svm}{SVM}{support vector machine} +\end{verbatim} +\end{example} + +The \sty{glossaries-prefix} package provides convenient commands to +use these prefixes with commands such as \ics{gls}. Note that the +prefix is not considered part of the \gls{linktext}, so it's not +included in the hyperlink (where hyperlinks are enabled). The +options and any star or plus modifier are passed on to the \glslike\ +command. (See \sectionref{sec:glslink} for further details.) + +\begin{definition}[\DescribeMacro\pgls] +\cs{pgls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This is inserts the value of the \gloskey{prefix} key (or +\gloskey{prefixfirst} key, on \gls{firstuse}) in front of +\cs{gls}\oarg{options}\marg{label}\oarg{insert}. + +\begin{definition}[\DescribeMacro\Pgls] +\cs{Pgls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +If the \gloskey{prefix} key (or \gloskey{prefixfirst}, on +\gls*{firstuse}) has been set, this displays the value of that key +with the first letter converted to upper case followed by +\cs{gls}\oarg{options}\marg{label}\oarg{insert}. If that key hasn't +been set, this is equivalent to +\ics{Gls}\oarg{options}\marg{label}\oarg{insert}. + +\begin{definition}[\DescribeMacro\PGLS] +\cs{PGLS}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +As \cs{pgls} but converts the prefix to upper case and uses +\ics{GLS} instead of \cs{gls}. + +\begin{definition}[\DescribeMacro\pglspl] +\cs{pglspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This is inserts the value of the \gloskey{prefixplural} key (or +\gloskey{prefixfirstplural} key, on \gls{firstuse}) in front of +\cs{glspl}\oarg{options}\marg{label}\oarg{insert}. + +\begin{definition}[\DescribeMacro\Pglspl] +\cs{Pglspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +If the \gloskey{prefixplural} key (or \gloskey{prefixfirstplural}, on +\gls*{firstuse}) has been set, this displays the value of that key +with the first letter converted to upper case followed by +\cs{glspl}\oarg{options}\marg{label}\oarg{insert}. If that key hasn't +been set, this is equivalent to +\ics{Glspl}\oarg{options}\marg{label}\oarg{insert}. + +\begin{definition}[\DescribeMacro\PGLSpl] +\cs{PGLSpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +As \cs{pglspl} but converts the prefix to upper case and uses +\ics{GLSpl} instead of \cs{glspl}. + +\begin{example}{Using Prefixes}{ex:prefixes} +Continuing from Example~\ref{ex:determiners}, now that I've defined +my entries, I~can use them in the text via the above commands: +\begin{verbatim} +First use: \pgls{svm}. Next use: \pgls{svm}. +Singular: \pgls{sample}, \pgls{oeil}. +Plural: \pglspl{sample}, \pglspl{oeil}. +\end{verbatim} +which produces: +\begin{quote} +First use: a~support vector machine (SVM). Next +use: an SVM. +Singular: a~sample, l'oeil. Plural: the samples, les yeux. +\end{quote} +For a complete document, see \samplefile{-prefix}. +\end{example} + +This package also provides the commands described below, none of +which perform any check to determine the entry's existence. + +\begin{definition}[\DescribeMacro\ifglshasprefix] +\cs{ifglshasprefix}\marg{label}\marg{true part}\marg{false part} +\end{definition} +Does \meta{true part} if the entry identified by \meta{label} has a +non-empty value for the \gloskey{prefix} key. + +This package also provides the following commands: +\begin{definition}[\DescribeMacro\ifglshasprefixplural] +\cs{ifglshasprefixplural}\marg{label}\marg{true part}\marg{false part} +\end{definition} +Does \meta{true part} if the entry identified by \meta{label} has a +non-empty value for the \gloskey{prefixplural} key. + +\begin{definition}[\DescribeMacro\ifglshasprefixfirst] +\cs{ifglshasprefixfirst}\marg{label}\marg{true part}\marg{false part} +\end{definition} +Does \meta{true part} if the entry identified by \meta{label} has a +non-empty value for the \gloskey{prefixfirst} key. + +\begin{definition}[\DescribeMacro\ifglshasprefixfirstplural] +\cs{ifglshasprefixfirstplural}\marg{label}\marg{true part}\marg{false part} +\end{definition} +Does \meta{true part} if the entry identified by \meta{label} has a +non-empty value for the \gloskey{prefixfirstplural} key. + +\begin{definition}[\DescribeMacro\glsentryprefix] +\cs{glsentryprefix}\marg{label} +\end{definition} +Displays the value of the \gloskey{prefix} key for the entry given +by \meta{label}. + +\begin{definition}[\DescribeMacro\glsentryprefixfirst] +\cs{glsentryprefixfirst}\marg{label} +\end{definition} +Displays the value of the \gloskey{prefixfirst} key for the entry given +by \meta{label}. + +\begin{definition}[\DescribeMacro\glsentryprefixplural] +\cs{glsentryprefixplural}\marg{label} +\end{definition} +Displays the value of the \gloskey{prefixplural} key for the entry given +by \meta{label}. (No check is performed to determine if the entry +exists.) + +\begin{definition}[\DescribeMacro\glsentryprefixfirstplural] +\cs{glsentryprefixfirstplural}\marg{label} +\end{definition} +Displays the value of the \gloskey{prefixfirstplural} key for the entry given +by \meta{label}. (No check is performed to determine if the entry +exists.) + +There are also variants that convert the first letter to upper +case\footnote{The earlier caveats about initial non-Latin characters +apply.}: +\begin{definition}[\DescribeMacro\Glsentryprefix] +\cs{Glsentryprefix}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro\Glsentryprefixfirst] +\cs{Glsentryprefixfirst}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro\Glsentryprefixplural] +\cs{Glsentryprefixplural}\marg{label} +\end{definition} + +\begin{definition}[\DescribeMacro\Glsentryprefixfirstplural] +\cs{Glsentryprefixfirstplural}\marg{label} +\end{definition} + +\begin{important} +As with analogous commands such as \ics{Glsentrytext}, these +commands aren't expandable so can't be used in PDF bookmarks. +\end{important} + +\begin{example}{Adding Determiner to Glossary Style}{ex:plist} +You can use the above commands to define a new glossary style that +uses the determiner. For example, the following style is a slight +modification of the \glostyle{list} style that inserts the prefix +before the name: +\begin{verbatim} +\newglossarystyle{plist}{% + \setglossarystyle{list}% + \renewcommand*{\glossentry}[2]{% + \item[\glsentryitem{##1}% + \Glsentryprefix{##1}% + \glstarget{##1}{\glossentryname{##1}}] + \glossentrydesc{##1}\glspostdescription\space ##2}% +} +\end{verbatim} +\end{example} + +\chapter{Accessibility Support}\label{sec:accsupp} + +Limited accessibility support is provided by the accompanying +\sty{glossaries-accsupp} package, but note that this package is +experimental and it requires the \sty{accsupp} package +which is also listed as experimental. This package defines +additional keys that may be used when defining glossary entries. +The keys are as follows: +\begin{description} +\item[{\gloskey{access}}] The replacement text corresponding to +the \gloskey{name} key. + +\item[{\gloskey{textaccess}}] The replacement text corresponding +to the \gloskey{text} key. + +\item[{\gloskey{firstaccess}}] The replacement text corresponding +to the \gloskey{first} key. + +\item[{\gloskey{pluralaccess}}] The replacement text corresponding +to the \gloskey{plural} key. + +\item[{\gloskey{firstpluralaccess}}] The replacement text corresponding +to the \gloskey{firstplural} key. + +\item[{\gloskey{symbolaccess}}] The replacement text corresponding +to the \gloskey{symbol} key. + +\item[{\gloskey{symbolpluralaccess}}] The replacement text corresponding +to the \gloskey{symbolplural} key. + +\item[{\gloskey{descriptionaccess}}] The replacement text corresponding +to the \gloskey{description} key. + +\item[{\gloskey{descriptionpluralaccess}}] The replacement text corresponding +to the \gloskey{descriptionplural} key. + +\item[{\gloskey{longaccess}}] The replacement text corresponding to +the \gloskey{long} key (used by \ics{newacronym}). + +\item[{\gloskey{shortaccess}}] The replacement text corresponding to +the \gloskey{short} key (used by \ics{newacronym}). + +\item[{\gloskey{longpluralaccess}}] The replacement text corresponding to +the \gloskey{longplural} key (used by \ics{newacronym}). + +\item[{\gloskey{shortpluralaccess}}] The replacement text corresponding to +the \gloskey{shortplural} key (used by \ics{newacronym}). + +\end{description} +For example: +\begin{verbatim} +\newglossaryentry{tex}{name={\TeX},description={Document +preparation language},access={TeX}} +\end{verbatim} +Now \verb|\gls{tex}| will be equivalent to +\begin{verbatim} +\BeginAccSupp{ActualText=TeX}\TeX\EndAccSupp{} +\end{verbatim} +The sample file \samplefile{accsupp} illustrates the +\sty{glossaries-accsupp} package. + +See \ifpdf section~\ref*{sec:code:accsupp} in \fi the documented code +(\texttt{glossaries-code.pdf}) for further details. I~recommend +that you also read the \sty{accsupp} documentation. + +\chapter{Troubleshooting} +\label{sec:trouble} + +In addition to the sample files listed in \sectionref{sec:samples}, +the \styfmt{glossaries} package comes with some minimal example +files, \texttt{minimalgls.tex}, \texttt{mwe-gls.tex}, +\texttt{mwe-acr.tex} and \texttt{mwe-acr-desc.tex}, which can be +used for testing. These should be located in the \texttt{samples} +subdirectory (folder) of the \styfmt{glossaries} documentation +directory. The location varies according to your operating system +and \TeX\ installation. For example, on my Linux partition it can +be found in \texttt{/usr\slash local\slash texlive\slash +2014\slash texmf-dist\slash doc\slash latex\slash glossaries/}. +The \gls{makeglossariesgui} application can also be used to test for +various problems. +Further information on debugging \LaTeX\ code is available at +\url{http://www.dickimaw-books.com/latex/minexample/}. + +If you have any problems, please first consult the +\urlfootref{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries} FAQ}. If that +doesn't help, try posting your query to somewhere like the +\texttt{comp.text.tex} newsgroup, the +\urlfootref{http://www.latex-community.org/}{\LaTeX\ Community Forum} or +\urlfootref{http://tex.stackexchange.com/}{\TeX\ on StackExchange}. +Bug reports can be submitted via +\urlfootref{http://www.dickimaw-books.com/bug-report.html}{my package bug report form}. + +\PrintIndex + +\end{document} |