summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/glossaries/glossaries-user.tex')
-rw-r--r--macros/latex/contrib/glossaries/glossaries-user.tex4251
1 files changed, 2337 insertions, 1914 deletions
diff --git a/macros/latex/contrib/glossaries/glossaries-user.tex b/macros/latex/contrib/glossaries/glossaries-user.tex
index f4dc52e08e..cefb8116a9 100644
--- a/macros/latex/contrib/glossaries/glossaries-user.tex
+++ b/macros/latex/contrib/glossaries/glossaries-user.tex
@@ -198,7 +198,7 @@
\newcommand{\gallery}[2]{\href{https://www.dickimaw-books.com/gallery/#1}{#2}}
\newcommand{\galleryurl}[1]{\gallery{#1}{\nolinkurl{https://www.dickimaw-books.com/gallery/#1}}}
-\newcommand{\gallerytopic}[1]{\galleryurl{\##1}}
+\newcommand{\gallerytopic}[1]{\gallery{\##1}{\styfmt{#1} gallery}}
\newcommand*{\bibglsgallery}[2][\gallerytitle]{%
\def\gallerytitle{#2}%
@@ -501,6 +501,17 @@ user2={sanitization\protect\iterm{sanitize}}%
description={An alphabet consisting of \glspl{nonlatinchar}.}
}
+\newglossaryentry{UTF-8}{%
+ name={UTF-8\itermdef{UTF-8}},
+ text={UTF-8},
+ sort={UTF-8},
+ description={A variable-width character encoding. This means that
+some characters are represented by more that one byte. \XeLaTeX\ and
+\LuaLaTeX\ treat the multi-byte sequence as a single token, but the
+older \LaTeX\ formats have single-byte tokens, which causes
+complications. Related blog article: \href{https://www.dickimaw-books.com/blog/binary-files-text-files-and-file-encodings/}{Binary Files, Text Files and File Encodings}.}
+}
+
\newglossaryentry{glossaries-extra}{%
name={\styfmt{glossaries-extra}},
sort={glossaries-extra},
@@ -671,11 +682,11 @@ and~\hyperlink{option#2}{#2}}
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for glossaries.sty v4.46}
+ \title{User Manual for glossaries.sty v4.47}
\author{Nicola L.C. Talbot\\%
\href{http://www.dickimaw-books.com/contact}{\nolinkurl{dickimaw-books.com/contact}}}
- \date{2020-03-19}
+ \date{2021-09-20}
\maketitle
\begin{abstract}
@@ -750,18 +761,13 @@ how to adjust the settings.
\end{important}
\noindent
-The \styfmt{glossaries} bundle comes with the following documentation:
+The \styfmt{glossaries} bundle includes 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.
@@ -769,9 +775,7 @@ 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.46}.
-
-\item[INSTALL] Installation instructions.
+\qt{Documented Code for glossaries v4.47}.
\item[CHANGES] Change log.
@@ -785,7 +789,7 @@ Related resources:
\item \href{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries}
FAQ}
-\item \gallerytopic{glossaries}{\styfmt{glossaries} gallery}
+\item \gallerytopic{glossaries}
\item
\gallery{glossaries-styles/}{a summary of all glossary styles provided by \styfmt{glossaries} and
@@ -993,7 +997,7 @@ options are specific to \gls{glossaries-extra}. Other options are
passed to the base \styfmt{glossaries} package.
\begin{xtr}
-In this document, commands and options displayed in teal, such as
+In this user manual, commands and options displayed in teal, such as
\xtrcs{newabbreviation} and \pkgopt*{stylemods}, are only available with
the \gls{glossaries-extra} package. There are also some commands and options (such
as \cs{makeglossaries} and \pkgopt{symbols}) that are provided by the
@@ -1022,7 +1026,7 @@ 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
+mechanism works. An \gls{indexingapp} is used to generate 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
@@ -1038,9 +1042,6 @@ The remainder of this introductory section covers the following:
\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.
@@ -1053,6 +1054,9 @@ wish to write in a language other than English.
\end{itemize}
+There are some sample documents provided with this package. They are
+described in \sectionref{sec:samples}.
+
\section{Indexing Options}
\label{sec:indexingoptions}
@@ -1173,6 +1177,7 @@ format. \cs{newglossaryentry} should not be used explicitly.\par
\optionsec[\TeX]{TeX}
+This option isn't generally recommended for reasons given below.
Example Document:
\begin{verbatim}
\documentclass{article}
@@ -1198,7 +1203,8 @@ and load it in the preamble with \ics{loadglsentries} (\emph{after}
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
+\glspl{exlatinalph} or \glspl{nonlatinalph} and there's no guarantee
+that it will work with \gls{UTF-8}. 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
@@ -1232,6 +1238,7 @@ 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.
+Summary:
\begin{enumerate}
\item Add
\begin{verbatim}
@@ -1284,8 +1291,8 @@ 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
+with \gls{UTF-8} characters, especially for any sort values that start
+with a \gls{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
@@ -1319,6 +1326,7 @@ documentation for further details. See also the
\sectionref{sec:samplessort}.
\end{xtr}
+Summary:
\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:
@@ -1504,6 +1512,7 @@ of use\slash definition with \opt1. See the \gls{glossaries-extra}
documentation for further details.
\end{xtr}
+Summary:
\begin{enumerate}
\item Add the \pkgopt{xindy} option to the \styfmt{glossaries}
package option list:
@@ -1668,7 +1677,7 @@ or (with at least \gls{glossaries-extra} v1.37 and \gls{bib2gls} v1.8):
The \pkgopt+{nameref}{record} option is the best method.
(It's possible to use a hybrid of this method and \optsor23 with
-\pkgopt+{alsoindex}{record} but in general there is little need
+\pkgopt+{hybrid}{record} but in general there is little need
for this and it complicates the build process.)
Each resource set is loaded with \ics*{GlsXtrLoadResources}\oarg{options}.
@@ -1736,6 +1745,38 @@ Repository, which provides more extensive language support than
numerical value it will attempt to form ranges otherwise it will
simply list the locations.
+Summary:
+\begin{enumerate}
+ \item Use \gls{glossaries-extra} with the \pkgopt+{record} package
+option:
+\begin{verbatim}
+\usepackage[record]{glossaries-extra}
+\end{verbatim}
+
+ \item Use \cs*{GlsXtrLoadResources} to identify the \filetype{bib}
+file(s) and \gls{bib2gls} options:
+\begin{verbatim}
+\GlsXtrLoadResources[src={terms.bib,abbreviations.bib},sort=en]
+\end{verbatim}
+
+ \item Put
+\begin{alltt}
+\cs*{printunsrtglossary}
+\end{alltt}
+where you want your list of entries to appear. Alternatively to
+display all glossaries use the iterative command:
+\begin{alltt}
+\cs*{printunsrtglossaries}
+\end{alltt}
+
+\item Run \LaTeX\ on your document.
+
+\item Run \gls{bib2gls} with just the document base name.
+
+\item Run \LaTeX\ on your document.
+
+\end{enumerate}
+
See \bibglsbegin\ or the \gls{bib2gls} user manual for further
details of this method, and
also \href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating
@@ -1766,7 +1807,11 @@ Example document:
This method is best used with the package option \pkgopt[none]{sort}
(as shown above). There's no \qt{activation} command (such as \cs{makeglossaries}
-for \optsand23).
+for \optsand23). In general it's best to use a style that doesn't
+show letter group headings. If you do want letter headings then you
+must ensure that you have defined your entries in alphabetical
+order, and use \XeLaTeX\ or \LuaLaTeX\ if you require \gls{UTF-8} letter
+groups.
All entries must be defined before the glossary is displayed
(preferably in the preamble) in the required order, and child
@@ -2279,6 +2324,44 @@ For example:
description={eu, nulla}}
\end{verbatim}
+\item[example-glossaries-longchild.tex] (New to v4.47.) These entries all
+have long descriptions and there are some child entries. For example:
+\begin{verbatim}
+\newglossaryentry{longsedmattis}{name={sed mattis},
+ description={erat sit amet dolor sit amet, consectetuer adipiscing elit.
+ Ut purus elit, vestibulum ut, placerat ac, adipiscing vitae, felis.
+ Curabitur dictum gravida mauris.}}
+
+\newglossaryentry{longgravida}{parent={longsedmattis},name={gravida},
+ description={malesuada libero, nonummy eget, consectetuer id, vulputate a,
+ magna. Donec vehicula augue eu neque. Pellentesque habitant morbi tristique
+senectus et netus et malesuada fames ac turpis egestas. Mauris ut
+leo.}}
+\end{verbatim}
+
+\item[example-glossaries-childmultipar.tex] (New to v4.47.) This
+consists of parent entries with single paragraph descriptions and
+child entries with multi-paragraph descriptions. Some entries have
+the \gloskey{user1} key set to the name of an image file provided by
+the \sty{mwe} package. For example:
+\begin{verbatim}
+\newglossaryentry{hiersedmattis}{name={sed mattis},user1={example-image},
+ description={Erat sit amet dolor sit amet, consectetuer adipiscing elit.
+ Ut purus elit, vestibulum ut, placerat ac, adipiscing vitae, felis. Curabitur
+dictum gravida mauris. Ut pellentesque augue sed urna. Vestibulum
+diam eros, fringilla et, consectetuer eu, nonummy id, sapien. Nullam
+at lectus. In sagittis ultrices mauris. Curabitur malesuada erat sit
+amet massa. Fusce blandit. Aliquam erat volutpat.}}
+
+\longnewglossaryentry{hierloremi-ii}
+{name={lorem 1--2},parent={hiersedmattis}}%
+{%
+Lorem ipsum ...
+
+Nam dui ligula...
+}
+\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},
@@ -2352,7 +2435,7 @@ 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}
+\documentclass[french]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}
@@ -2639,7 +2722,7 @@ if you have glossary entries that contain
details on \gls{xindy}, and see the \gls{bib2gls} user manual for
further details of that application.
-\subsubsection{Creating a New Language Module}
+\subsection{Creating a New Language Module}
\label{sec:newlang}
The \styfmt{glossaries} package now uses the \sty{tracklang} package
@@ -2793,10 +2876,10 @@ language file and make the appropriate changes, for example:
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
+while some users may use \gls{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.
+your preference on them, it's useful to provide a \gls{UTF-8} version for
+\XeLaTeX\ and \LuaLaTeX\ users.
The \texttt{glossaries-irish.ldf} file provides this as follows:
\begin{verbatim}
@@ -2842,7 +2925,7 @@ your root language label and \texttt{Irish} with the
There are now two extra files: \nolinkurl{glossaries-irish-noenc.ldf}
(no encoding information)
-and \nolinkurl{glossaries-irish-utf8.ldf} (UTF-8).
+and \nolinkurl{glossaries-irish-utf8.ldf} (\gls{UTF-8}).
These both define \cs{glossariescaptionsirish} but the \texttt{*-noenc.ldf} uses
\LaTeX\ accent commands:
@@ -2874,7 +2957,7 @@ These both define \cs{glossariescaptionsirish} but the \texttt{*-noenc.ldf} uses
}
\end{verbatim}
whereas the \texttt{*-utf8.ldf} replaces the accent commands with
-the appropriate UTF-8 characters.
+the appropriate \gls{UTF-8} characters.
\section{Generating the Associated Glossary Files}
@@ -3170,7 +3253,7 @@ For a complete list of options do \texttt{makeglossaries -{}-help}.
\begin{important}
When upgrading the \styfmt{glossaries} package, make sure you also
upgrade your version of \gls{makeglossaries}. The current version is
-4.45.
+4.47.
\end{important}
\subsection{Using the makeglossaries-lite Lua Script}
@@ -3422,9 +3505,15 @@ for every time an entry has been referenced.
If you need to gather labels for auto-completion, the
\pkgopt{writeglslabels} package option will create a file containing
the labels of all defined entries (regardless of whether or not the
-entry has been used in the document). The \gls{glossaries-extra}
+entry has been used in the document). As from v4.47, there is a
+similar option \pkgopt{writeglslabelnames} that writes both the
+label and name (separated by a tab).
+
+\begin{xtr}
+The \gls{glossaries-extra}
package also provides \pkgopt+{atom}{docdef}, which will create the
\filetype{glsdefs} file but will act like \pkgopt+{restricted}{docdef}.
+\end{xtr}
\subsection{Bib2Gls}
\label{sec:notedev.bib2gls}
@@ -3446,7 +3535,7 @@ not to run \gls{bib2gls}:
\end{alltt}
(It gets more complicated if both \ics*{glsxtr@resource} and
\cs{@istfilename} are present as that indicates the hybrid
-\pkgopt+{alsoindex}{record} option.)
+\pkgopt+{hybrid}{record} option.)
Remember that with \gls{bib2gls}, the entries will never be defined
on the first \LaTeX\ call (because their definitions are contained
@@ -3817,7 +3906,8 @@ will create a file called \cs{jobname}\texttt{.}\filetype{glslabels} at the end
of the document. This file simply contains a list of all defined
entry labels (including those in any ignored glossaries). It's
provided for the benefit of text editors that need to know labels
-for \Index{auto-completion}. (See also \gls{glossaries-extra}['s]
+for \Index{auto-completion}. If you also want the name, use
+\pkgopt{writeglslabelnames}. (See also \gls{glossaries-extra}['s]
\pkgopt+{atom}{docdef} package option.)
\begin{bib2gls}
@@ -3825,12 +3915,15 @@ Note that with \gls{bib2gls} the file will only contain the entries
that \gls{bib2gls} has selected from the \filetype{bib} files.
\end{bib2gls}
+\pkgoptsec{writeglslabelnames} Similar to the above but writes both
+the label and name (separated by a tab).
+
\xtrpkgoptsec[value]{undefaction}
The value may be one of:
\begin{description}
\item[\pkgoptfmt{error}] generate an error if a referenced entry is
- undefined (default, and only available setting with just
+ undefined (default, and the only available setting with just
\styfmt{glossaries});
\item[\pkgoptfmt{warn}] only warn if a referenced entry is
undefined (automatically activated with \opt4).
@@ -4252,7 +4345,7 @@ groups.
\xtrpkgoptsec[list]{stylemods}
-Load the \sty{glossaries-extra-stylemods} package and patch the
+Load the \sty{glossaries-extra-stylemods} package, which patches the
predefined styles. The \meta{list} argument is optional. If present,
this will also load \styfmt{glossary-\meta{element}.sty} for each
\meta{element} in the comma-separated \meta{list}.
@@ -4263,7 +4356,7 @@ this will also load \styfmt{glossary-\meta{element}.sty} for each
\pkgoptsec[value]{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 if this
+cross-referenced entry using \ics{glssee}. This means that if this
key is used in an entry definition 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
@@ -4362,17 +4455,30 @@ and \texttt{acronym} categories. (Instead of using the
\xtrpkgoptsec[boolean]{indexcrossrefs}
-If \pkgoptfmt{true}, this will automatically index any
+If \pkgoptfmt{true}, this will automatically index (\ics{glsadd}) any
cross-referenced entries that haven't been marked as used at the end
of the document. Increases document build time. See
\gls{glossaries-extra} manual for further details.
+\begin{bib2gls}
+Note that \gls{bib2gls} can automatically find dependent entries
+when it parses the \filetype{bib} file. Use the \xtrfont{selection} option to
+\ics*{GlsXtrLoadResources} to determine the selection of
+dependencies.
+\end{bib2gls}
+
\xtrpkgoptsec[boolean]{autoseeindex}
If \pkgoptfmt{true}, makes the \gloskey{see} and
\xtrgloskey{seealso} keys automatically index the cross-reference
-when the entry is defined (default, and the only option with just
-the base \styfmt{glossaries} package).
+(with \ics{glssee}) when the entry is defined (default, and the only
+option with just the base \styfmt{glossaries} package).
+
+\begin{bib2gls}
+With \gls{bib2gls}, use the \xtrfont{selection} option to
+\ics*{GlsXtrLoadResources} to determine the selection of
+dependencies.
+\end{bib2gls}
\xtrpkgoptsec[value]{record}
@@ -4388,10 +4494,11 @@ for \optsto13;
\item[\pkgoptfmt{nameref}] like \pkgoptfmt{only} but provides extra
information that allows the associated title to be used instead of
-the location number;
+the location number and provides better support for hyperlinked
+locations;
-\item[\pkgoptfmt{alsoindex}] a hybrid approach where \gls{bib2gls}
-is begin used to fetch entries from a \filetype{bib} file but
+\item[\pkgoptfmt{hybrid}] a hybrid approach where \gls{bib2gls}
+is used to fetch entries from a \filetype{bib} file but
\gls{makeindex} or \gls{xindy} are used for the indexing. This
requires a more complicated document build and isn't recommended.
\end{description}
@@ -4415,9 +4522,10 @@ is indexed within the float before the caption.)
This valueless option is primarily intended for use with
\gls{bib2gls} and \sty{hyperref} allowing the page location
-hyperlink to the relevant point in the page (rather than the top of
-the page). Unexpected results will occur with other indexing
-methods. See \gls{glossaries-extra} manual for further details.
+hyperlink target to be set to the relevant point within the page
+(rather than the top of the page). Unexpected results will occur
+with other indexing methods. See \gls{glossaries-extra} manual for
+further details.
\section{Sorting Options}
\label{sec:pkgopts-sort}
@@ -4753,7 +4861,7 @@ 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
+correspond with \sty{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.
@@ -5085,7 +5193,7 @@ of acronyms using:
\end{definition}
\begin{xtr}
-This option is incompatible with \gls{glossaries-extra}['s]
+This option and associated commands are incompatible with \gls{glossaries-extra}['s]
abbreviation mechanism.
\end{xtr}
@@ -5100,7 +5208,7 @@ Alternatively you can use:
The \gls{glossaries-extra} package provides additional shortcuts.
\end{xtr}
-\subsection{Deprecated Acronym Style Options}
+\section{Deprecated Acronym Style Options}
\label{sec:pkgopts-old-acronym}
The package options listed in this section are now deprecated but
@@ -5308,14 +5416,25 @@ unexpected results. If you try changing the sort option after you have
started to define entries, you may get unexpected results.
\end{important}
+\begin{xtr}
+With \gls{glossaries-extra}, use \ics*{glossariesextrasetup}
+instead.
+\end{xtr}
+
\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.)
+In the preamble you need to indicate which method you want to use to
+generate the glossary (or glossaries). The available options with
+both \styfmt{glossaries} and \gls{glossaries-extra} are
+summarized in \sectionref{sec:indexingoptions}. This chapter
+documents \optsto13, which are provided by the base package. See the
+\gls{glossaries-extra} and \gls{bib2gls} manuals for the full
+documentation of the other options.
+
+If you don't need to display any glossaries, for example, if you are
+just using the \styfmt{glossaries} package to enable consistent
+formatting, then skip ahead to \sectionref{sec:newglosentry}.
\section[Option 1]{\ifpdf\opt1\else Option 1\fi}
\label{sec:setupopt1}
@@ -5371,8 +5490,8 @@ Note that if you have a custom \filetype{xdy} file created when using
\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
+\ics{jobname}\texttt{.}\filetype{ist} (\opt2) or
+\ics{jobname}\texttt{.}\filetype{xdy} (\opt3). This name may be
changed using:
\begin{definition}[\DescribeMacro{\setStyleFile}]
\cs{setStyleFile}\marg{name}
@@ -5414,6 +5533,19 @@ See \sectionref{sec:numberlists} for further information about
\chapter{Defining Glossary Entries}
\label{sec:newglosentry}
+\begin{bib2gls}
+If you want to use \gls{bib2gls}, entries must be defined in
+\filetype{bib} files using the syntax described in the \gls{bib2gls}
+user manual.
+\end{bib2gls}
+
+Acronyms are covered in \sectionref{sec:acronyms} but they use the
+same underlying mechanism as all the other entries, so it's a good
+idea to read this chapter first. The keys provided for
+\cs{newglossaryentry} can also be used in the optional argument of
+\cs{newacronym}, although some of them, such as \gloskey{first} and
+\gloskey{plural}, interfere with the acronym styles.
+
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}
@@ -5556,12 +5688,28 @@ is set to the same as the \gloskey{description} key.
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.
+This key is automatically set by \cs{newacronym}. Although it is
+possible to override it by using \gloskey{text} in the optional
+argument of \cs{newacronym}, it will interfere with the acronym
+style and cause unexpected results.
+
\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}.
+\gloskey{first} value won't be used with \ics{gls}.
+
+You may prefer to use abbreviations (\sectionref{sec:acronyms})
+or the category post-link hook (\ics*{glsdefpostlink}) provided by
+\gls{glossaries-extra} if you would like to automatically append
+content on \firstuse\ in a consistent manner. See, for example,
+\gallery{index.php?label=sample-units}{Gallery: Units
+(\styfmt{glossaries-extra.sty})}.
+
+Although it is possible to use \gloskey{first} in the optional
+argument of \cs{newacronym}, it can interfere with the acronym
+style and cause unexpected results.
\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
@@ -5569,6 +5717,11 @@ 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}.
+Although it is possible to use \gloskey{plural} in the optional
+argument of \cs{newacronym}, it can interfere with the acronym
+style and cause unexpected results. Use \gloskey{shortplural}
+instead, if the default value is inappropriate.
+
\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
@@ -5579,6 +5732,11 @@ 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}.
+Although it is possible to use \gloskey{firstplural} in the optional
+argument of \cs{newacronym}, it can interfere with the acronym
+style and cause unexpected results. Use \gloskey{shortplural}
+and \gloskey{longplural} instead, if the default value is inappropriate.
+
\importantpar
Note: prior to version 1.13, the default value of
\gloskey{firstplural} was always taken by appending \qt{s} to the
@@ -5595,12 +5753,15 @@ 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
+\item[{\gloskey{sort}}] This value indicates the text to be used by
+the sort comparator when ordering all the entries. 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}|).
+\pkgopt[def]{sort} and \pkgopt[use]{sort} have been used.
+With \opt2 it's best to use the \gloskey{sort} key if the
+\gloskey{name} contains commands (e.g.\ \verb|\ensuremath{\alpha}|)
+and with \optsand13, it's strongly recommended as the indexing may
+fail if you don't (see below).
+
You can also override the \gloskey{sort} key by redefining
\ics{glsprestandardsort} (see \sectionref{sec:pkgopts-sort}).
@@ -5652,7 +5813,7 @@ Similarly if you use the \sty{inputenc} package:
This is equivalent to
\begin{alltt}
\cs{newglossaryentry}\mgroup{elite}\mgroup{\%
- name=i\mgroup{\mgroup{\'e}lite},
+ name=\mgroup{\mgroup{\'e}lite},
description=\mgroup{select group of people},
sort=elite
}
@@ -5706,9 +5867,48 @@ this entry. Conversely, if you have used the package option
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.
+\item[{\gloskey{see}}]
+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. (See \sectionref{sec:crossref}.)
+It was originally designed for synonyms that may not occur in the
+document text but needed to be included in the glossary in order to
+redirect the reader. Note that it doesn't index the cross-referenced
+entry (or entries) as that would interfere with their \glspl{numberlist}.
+
+\begin{important}
+Using the \gloskey{see} key will \emph{automatically add this entry
+to the glossary}, but will not automatically add the
+cross-referenced entry.
+\end{important}
+
+For example:
+\begin{verbatim}
+\newglossaryentry{courgette}{name={courgette},
+ description={variety of small marrow}}
+\newglossaryentry{zucchini}{name={zucchini},
+ description={(North American)},
+ see={courgette}}
+\end{verbatim}
+This defines two entries (courgette and zucchini) and automatically
+adds a cross-reference from zucchini to courgette. (That is, it adds
+\qt{\emph{see} courgette} to zucchini's \gls{numberlist}.) This
+doesn't automatically index courgette since this would create an
+unwanted location in courgette's \gls{numberlist}. (Page~1, if the
+definitions occur in the preamble.)
+
+Note that while it's possible to put the cross-reference in the
+description instead, for example:
+\begin{verbatim}
+\newglossaryentry{zucchini}{name={zucchini},
+ description={(North American) see \gls{courgette}}}
+\end{verbatim}
+this won't index the zucchini entry, so if zucchini isn't indexed
+elsewhere (with commands like \cs{gls} or \cs{glsadd}) then it won't
+appear in the glossary even if courgette does.
+
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
@@ -5720,12 +5920,6 @@ 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
@@ -5740,7 +5934,14 @@ 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.
+consider using \opt4. See also the FAQ item
+\href{https://www.dickimaw-books.com/faq.php?action=view&category=glossaries&itemlabel=whyseekeyautoindex}{Why does the see key automatically index the entry?}
+
+\begin{bib2gls}
+The analogous \gls{bib2gls} \gloskey{see} field (and \xtrgloskey{seealso}) have a
+slightly different meaning. The \resourceopt{selection} resource option
+determines the behaviour.
+\end{bib2gls}
\item[{\xtrgloskey{seealso}}]
This key is only available with \gls{glossaries-extra} and is
@@ -5756,8 +5957,12 @@ another form of cross-referencing. An entry can be aliased to
another entry with \texttt{alias=\marg{label}}. This behaves like
\texttt{see=\marg{label}} but also alters the behaviour of commands
like \cs{gls} so that they index the entry given by \meta{label}
-instead of the original entry. More variations with the key are
-available with \gls{bib2gls}.
+instead of the original entry. (See, for example,
+\gallery{index.php?label=aliases}{Gallery: Aliases}.)
+
+\begin{bib2gls}
+More variations with the key are available with \gls{bib2gls}.
+\end{bib2gls}
\item[\xtrgloskey{category}]
This key is only available with \gls{glossaries-extra} and is used
@@ -5809,8 +6014,8 @@ package:
\cs{newglossaryentry}\mgroup{elite}\mgroup{name=\mgroup{\mgroup{\'e}lite},
description=\mgroup{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
+(This doesn't apply for \XeLaTeX\ or \LuaLaTeX\ documents.
+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
@@ -6648,7 +6853,7 @@ 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.)
+definitions if necessary.)
\subsection{Technical Issues}
\label{sec:techissues}
@@ -6661,7 +6866,11 @@ 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.
+being looked up before the entry has been defined. This means that
+it's not possible to display the content of the glossary unless the
+entry definitions are saved on the previous \LaTeX\ run and can be
+picked up at the start of the \env{document} environment on the next run
+(in a similar way that \cs{label} and \cs{ref} work).
\item If you use a package, such as \sty{babel}, that makes
certain characters active at the start of the \env{document}
@@ -6683,19 +6892,21 @@ 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.
+(\cs{jobname}\texttt{.}\filetype{glsdefs}) which is then read in at the start
+of the document on the next run. 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
+modification in \cs{printglossary} (if it occurs at the start of the
+document); 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).
+occur.
+
+Version 4.47 has introduced changes that have removed some of
+the issues involved, and there are now warning messages if there is an
+attempt to multiple define the same entry label.
The \gls{glossaries-extra} package provides a setting (but only for
\optsand23) that allows \cs{newglossaryentry} to occur in the
@@ -6730,488 +6941,55 @@ 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}
+\chapter{Referencing Entries in the Document}
+\label{sec:usingentries}
-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}}.
+Once you have defined a glossary entry using a command like
+\ics{newglossaryentry} (\sectionref{sec:newglosentry}) or
+\ics{newacronym} (\sectionref{sec:acronyms}), you can refer to that
+entry in the document with one of the provided commands that are
+describe in this manual. (There are some additional commands
+provided by \gls{glossaries-extra}.) The text produced at that point
+in the document is determined by the command and can also be
+governed by whether or not the entry has been
+\glsdisp{firstuseflag}{marked as used}.
-\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.
+Some of these commands are more complicated than others. Many of
+them are robust and can't be used in fully expandable contexts, such
+as in PDF bookmarks.
-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
-\filetype{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:
+The commands are broadly divided into:
\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).
+\item Those that display text in the document (where the formatting
+can be adjusted by a style or hook) and also index the
+entry (so that it's added to the document) are described in
+\sectionref{sec:glslink}. This set of commands can
+be further sub-divided into those that mark the entry as having been
+used (the \cs{gls}-like commands, \sectionref{sec:gls-like}) and those that don't
+(the \cs{glstext}-like commands, \sectionref{sec:glstext-like}).
+
+\item Those that display text in the document without indexing or applying any
+additional formatting (\sectionref{sec:glsnolink}).
\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
-\begin{alltt}
-\cs{glsaddprotectedpagefmt}\marg{internal cs name}
-\end{alltt}
-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 \xindyattr{: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}
+There are additional commands specific to entries defined with
+\cs{newacronym} that are described in \sectionref{sec:longshortfull}.
-\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|main} 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}
+\section{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.)
+The text which appears at the point in the document when using any
+of the commands described in \sectionref{sec:gls-like} or
+\sectionref{sec:glstext-like} 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
@@ -7246,11 +7024,13 @@ command or use \sty{hyperref}'s \ics{texorpdfstring}. Examples:
\chapter[An overview of Perl]{An overview of \gls{perl}}
\chapter{An overview of \texorpdfstring{\gls{perl}}{Perl}}
\end{verbatim}
+\begin{xtr}
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.
+\end{xtr}
If you want the \gls{linktext} to produce a hyperlink to the
corresponding entry details in the glossary, you should load the
@@ -7338,7 +7118,7 @@ other key that you plan to access through these commands.
\cs{glssymbol}.)
\end{important}
-The keys listed below are available for the optional argument.
+The keys listed below are available for the optional first argument.
The \gls{glossaries-extra} package provides additional keys.
(See the \gls*{glossaries-extra} manual for further details.)
\begin{description}
@@ -7500,7 +7280,7 @@ The \gls{linktext} isn't scoped by default with just the base
declarations in the \gls{linktext} may affect subsequent text.
\end{important}
-\section{The \cs{gls}-Like Commands (First Use Flag Queried)}
+\subsection{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
@@ -7779,7 +7559,7 @@ 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)}
+\subsection{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
@@ -8025,7 +7805,7 @@ There are also analogous uppercasing commands:
\cs{GLSuservi}\oarg{options}\marg{text}\oarg{insert}
\end{definition}
-\section{Changing the format of the link text}
+\subsection{Changing the format of the link text}
\label{sec:glsdisplay}
\begin{xtr}
@@ -8305,7 +8085,7 @@ 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}
+\subsection{Enabling and disabling hyperlinks to glossary entries}
\label{sec:disablehyperlinks}
If you load the \sty{hyperref} or \sty{html} packages prior to
@@ -8454,326 +8234,7 @@ 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}
-If you are using \gls{bib2gls} with \gls{glossaries-extra}, you
-can't use \cs{glsaddall}. Instead use the \optfmt{selection=all}
-resource option to select all entries in the given \filetype{bib} files.
-
-\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=glsignore]} 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.
-
-\begin{important}
-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.
-\end{important}
-
-With \gls{glossaries-extra} and \gls{bib2gls}, \texttt{glsignore}
-indicates an \qt{ignored location} which influences selection but
-isn't added to the location list. In this case, if you use
-\optfmt{selection=all} then only those entries that have been
-explicitly indexed in the document will have location lists. The
-other entries that were selected as a result of
-\optfmt{selection=all} won't have location lists.
-
-Base \sty{glossaries} package only:
-\begin{verbatim}
-\documentclass{article}
-\usepackage{glossaries}
-\makeglossaries
-\newglossaryentry{cat}{name={cat},description={feline}}
-\newglossaryentry{dog}{name={dog},description={canine}}
-\begin{document}
-\gls{cat}.
-\printglossaries
-\glsaddallunused % <- make sure dog is also listed
-\end{document}
-\end{verbatim}
-Corresponding \gls{glossaries-extra} and \gls{bib2gls} document code:
-\begin{verbatim}
-\documentclass{article}
-\usepackage[record]{glossaries-extra}
-\GlsXtrLoadResources[src={entries},selection=all]
-\begin{document}
-\gls{cat}.
-\printunsrtglossaries
-\end{document}
-\end{verbatim}
-With the file \texttt{entries.bib}:
-\begin{verbatim}
-@entry{cat,name={cat},description={feline}}
-@entry{dog,name={dog},description={canine}}
-\end{verbatim}
-
-\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}|.
-
-Note that with \gls{bib2gls}, there are special dual entry types
-that implement this behaviour. That is, if an entry is referenced
-then its corresponding dual entry will automatically be selected as
-well. So there is less need for \cs{glsadd} with \gls{bib2gls}.
-(Although it can still be useful, as shown in \opt6.)
-\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{prompt}
-pdflatex filename
-makeglossaries filename
-pdflatex filename
-makeglossaries filename
-pdflatex filename
-\end{prompt}
-
-\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}
+\section{Using Glossary Terms Without Links}
\label{sec:glsnolink}
The commands described in this section display entry details without
@@ -9092,10 +8553,10 @@ between the final two elements. The defaults are
\begin{important}
\cs{glsdisplaynumberlist} is fairly experimental. It works with
-\opt1, but for \optsor23 it only works when the default counter
+\optsand14, 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
+\sty{hyperref} if you choose \optsor14. If you try using this command
with \optsor23 and \sty{hyperref}, \cs{glsentrynumberlist} will be
used instead.
\end{important}
@@ -9104,978 +8565,6 @@ 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}
-\item[\opt1:]
-(Must be used with \ics{makenoidxglossaries} in the preamble.)
-\begin{definition}[\DescribeMacro\printnoidxglossaries]
-\cs{printnoidxglossaries}
-\end{definition}
-
-\item[\optsand23:]
-(Must be used with \ics{makeglossaries} in the preamble.)
-\begin{definition}[\DescribeMacro\printglossaries]
-\cs{printglossaries}
-\end{definition}
-\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}).
-
-\begin{important}
-While the external files are missing, \cs{printglossary} will just do
-\ics{null} for each missing glossary to assist dictionary style
-documents that just use \cs{glsaddall} without inserting any text.
-This use of \ics{null} ensures that all indexing information is
-written before the final page is shipped out. Once the external
-files are present \cs{null} will no longer be used. This can cause a
-spurious blank page on the first \LaTeX\ run before the glossary
-files have been created. Once these files are present, \cs{null}
-will no longer be used and so shouldn't cause interference for the
-final document.
-\end{important}
-
-\begin{xtr}
-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.
-\end{xtr}
-
-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.
-
-\item[{\xtrprintglosskey[\marg{label}]{label}}]
-This key is only available with \gls{glossaries-extra} and labels
-the glossary with \cs{label}\marg{label}. This is an alternative to
-the package option \pkgopt[autolabel]{numberedsection}
-
-\item[\xtrprintglosskey{target}] This is a boolean key only
-available with \gls{glossaries-extra}, which can be used to switch
-off the automatic hypertarget for each entry. (This refers to the
-target used by commands like \cs{gls} and \cs{glslink}.)
-
-This option is useful with \ics*{printunsrtglossary} as it allows
-the same list (of sub-list) of entries to be displayed multiple
-times without causing duplicate hypertarget names.
-
-\item[{\xtrprintglosskey[\marg{prefix}]{prefix}}]
-This key is only available with \gls{glossaries-extra} and provides
-another way of avoiding duplicate hypertarget names is to use a
-different prefix for those names. This locally redefines
-\ics{glolinkprefix} but note this will also affect the target for any entry
-referenced within the glossary with commands like \cs{gls},
-\cs{glslink} or \cs{glshypertarget}.
-
-\item[{\xtrprintglosskey[\marg{prefix}]{targetnameprefix}}]
-This key is only available with \gls{glossaries-extra}.
-This is similar to the \pkgoptfmt{prefix} option, but it alters the prefix of
-the hypertarget anchors without changing \ics{glslinkprefix} (so it
-won't change the hyperlinks for any entries referenced in the
-glossary).
-
-\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
-\gls{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 \ixindyattrs 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 \ixindyattrs 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
-\ixindyattrs 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.)
-
-\begin{xtr}
-The \gls{glossaries-extra} package provides a starred version of
-this command that allows hyperlinks (since ignored glossaries can be
-useful with \gls{bib2gls}). There is also an analogous
-\ics*{provideignoredglossary} command.
-\end{xtr}
-
-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}
@@ -10093,22 +8582,40 @@ 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
+key in the optional argument of \ics{printglossary} (or
\ics{printacronyms}). Alternatively consider using the
\gls{glossaries-extra} package's \pkgopt*{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:
+Acronyms use the same underlying mechanism as terms defined with
+\cs{newglossaryentry} so you can reference them with \ics{gls} and
+\ics{glspl}. The way the acronym is displayed on \gls{firstuse} is
+governed by the acronym style, which should be set before you define
+your acronyms. For example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\setacronymstyle{long-short}
+\newacronym{html}{HTML}{hypertext markup language}
+\newacronym{xml}{XML}{extensible markup language}
+\begin{document}
+First use: \gls{html} and \gls{xml}.
+Next use: \gls{html} and \gls{xml}.
+\end{document}
+\end{verbatim}
+If you don't specify a style, you will have a less-flexible, but
+backward-compatible, \qt{long (short)} style with just the base
+\styfmt{glossaries} package or the \abbrstyle{short-nolong} style
+(which only displays the short form on \gls{firstuse})
+with \gls{glossaries-extra}.
+
+Acronyms are defined using:
\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
+This creates 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},
@@ -10116,9 +8623,19 @@ argument. The \cs{newacronym} command also uses the \gloskey{long},
in \cs{newglossaryentry} to store the long and abbreviated forms and
their plurals.
+\begin{xtr}
+If you use \cs{newacronym} with \gls{glossaries-extra}, you need to
+first set the style with:
+\begin{alltt}
+\ics*{setabbreviationstyle}[acronym]\marg{style-name}
+\end{alltt}
+\end{xtr}
+
Note that the same restrictions on the entry \meta{label}
in \ics{newglossaryentry} also apply to \cs{newacronym}
(see \sectionref{sec:newglosentry}).
+Since \ics{newacronym} works like \ics{newglossaryentry}, you can use
+\ics{glsreset} to reset the \gls{firstuseflag}.
\begin{important}
If you haven't identified the specified glossary type as a list of
@@ -10130,7 +8647,8 @@ the list and \emph{reset the display style} for that glossary via
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.
+\ics{glsentryfmt}) before defining your entries. Alternatively, use
+\gls{glossaries-extra} to have better support for a mixed glossary.
\end{important}
The optional argument \marg{key-val list} allows you to specify
@@ -10151,23 +8669,24 @@ 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
-\icatattrs 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.
+using one of the pre-version 4.02 acronym styles (described in
+\sectionref{sec:pkgopts-old-acronym}).
+
+As with \gloskey{plural}, if \gloskey{longplural} is missing, it's
+obtained by appending \ics{glspluralsuffix} to the singular form. The
+short plural \gloskey{shortplural} is obtained (if 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}).
+
+\begin{xtr}
+A different approach is used by
+\styfmt{glossaries-extra}, which has \icatattrs category attributes
+to determine whether or not to append a suffix when forming the
+default value of \gloskey{shortplural}.
+\end{xtr}
\begin{important}
Since \cs{newacronym} sets \verb|type=\acronymtype|,
@@ -10181,6 +8700,7 @@ type as \verb|type=\glsdefaulttype| in the optional argument to
\begin{example}{Defining an Abbreviation}{ex:newacronym}
The following defines the abbreviation IDN:
\begin{verbatim}
+\setacronymstyle{long-short}
\newacronym{idn}{IDN}{identification number}
\end{verbatim}
\verb|\gls{idn}| will produce \qt{identification number (IDN)} on
@@ -10189,6 +8709,7 @@ of the \gls{smallcaps} acronym styles, described in
\sectionref{sec:setacronymstyle}, you need to use lower case
characters for the shortened form:
\begin{verbatim}
+\setacronymstyle{long-sc-short}
\newacronym{idn}{idn}{identification number}
\end{verbatim}
Now \verb|\gls{idn}| will produce \qt{identification number
@@ -10237,18 +8758,37 @@ or
\end{verbatim}
Similarly for the \glstextlike\ commands.
+\begin{xtr}
Other approaches are available with \gls{glossaries-extra}.
See the section \qt{Nested Links} in the \styfmt{glossaries-extra}
user manual.
+\end{xtr}
-\begin{important}
-The commands described below are similar to the \glstextlike\
-commands in that they don't modify the \firstuseflag.
+\section{Displaying the Long, Short and Full Forms (Independent of
+First Use)}
+\label{sec:longshortfull}
+
+It may be that you want the long, short or full form
+regardless of whether or not the acronym has already been used in
+the document. You can do so with the commands described in this
+section.
+
+The \cs{acr\ldots} commands described below are part of the set of
+\glstextlike\ commands. That is, they index and can form
+hyperlinks, but 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}
+(Including the above warning about nested links.)
+
+\begin{xtr}
+If you are using \gls{glossaries-extra}, don't use the commands
+described in this section. The \gls{glossaries-extra} package
+provides analogous \cs{glsxtr\ldots} or \cs{glsfmt\ldots}
+commands. For example, \cs{glsxtrshort} instead of \cs{acrshort}
+or, if needed in a heading, \cs{glsfmtshort}. (Similarly for the
+case-changing variants.)
+\end{xtr}
The optional arguments are the same as those for the \glstextlike\
commands, and there are similar star and plus variants that switch
@@ -10335,7 +8875,7 @@ where
\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
+deprecated for new acronym styles but is used by default for
backward compatibility if \cs{setacronymstyle}
(\sectionref{sec:setacronymstyle}) hasn't been used. (For further
details of these format commands see \ifpdf
@@ -10451,11 +8991,20 @@ 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}
+\section{Changing the Acronym 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{xtr}
+If you are using \gls{glossaries-extra}, don't use the commands
+described in this section. Use \ics*{setabbreviationstyle} to set
+the style. This uses a different (but more consistent) naming
+scheme. For example, \abbrstyle{long-noshort} instead of
+\acrstyle{dua}. See the \qt{Acronym Style Modifications} section and
+the \qt{Abbreviations} chapter in the \gls{glossaries-extra} manual
+for further details.
+\end{xtr}
+
+The acronym style is set using:
\begin{definition}[\DescribeMacro{\setacronymstyle}]
\cs{setacronymstyle}\marg{style name}
\end{definition}
@@ -10480,13 +9029,14 @@ For example:
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.
+If you need multiple abbreviation styles, then
+use the \gls{glossaries-extra} package, which has better
+abbreviation management. See, for example,
+\gallery{index.php?label=sample-name-font}{Gallery: Mixing Styles}.
\end{important}
-Unlike the default behaviour of \cs{newacronym}, the
-styles used via \cs{setacronymstyle} don't use the \gloskey{first}
+Unlike the backward-compatible default behaviour of \cs{newacronym}, the
+styles set 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
@@ -11260,8 +9810,8 @@ 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
-\gallery{sample-initialisms.shtml}{initialisms example}.)
+simpler way of doing this, which you may prefer to use. See
+\gallery{sample-initialisms.shtml}{Gallery: Initialisms}.)
\begin{example}{Abbreviations with Full Stops (Periods)}{ex:dotabbr}
As from version 4.16, there's now a hook (\ics{glspostlinkhook})
@@ -11527,6 +10077,14 @@ 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.
+Note that \cs{ifglsused} is unreliable with \gls{bib2gls} as the
+entry isn't defined on the first \LaTeX\ run, which means there's no
+way of determining if it has been used, so
+\gls{glossaries-extra} provides a similar command:
+\begin{definition}
+\ics*{GlsXtrIfUnusedOrUndefined}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+
\begin{important}
Be careful when using \glslike\ commands within an
environment or command argument that gets processed multiple times
@@ -11797,7 +10355,7 @@ 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
+any of the other commands that add information to the glossary file
(such as \cs{glsadd} or the \glstextlike\ commands) then the entry
won't appear in the glossary.
@@ -11837,7 +10395,7 @@ These entries are only used once: \cgls{sql}, \cgls{rdbms},
\end{document}
\end{verbatim}
After a complete document build (\texttt{latex}, \texttt{latex},
-\texttt{makeglossaries}, \texttt{latex}) the list of abbrevaitions only
+\texttt{makeglossaries}, \texttt{latex}) the list of abbreviations 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.
@@ -11854,6 +10412,1289 @@ With \gls{bib2gls} there's an analogous record counting set of
commands. See \gls{glossaries-extra} and \gls{bib2gls} manuals for further details.
\end{bib2gls}
+\chapter{Displaying a Glossary}
+\label{sec:printglossary}
+
+All defined glossaries may be displayed using:
+\begin{description}
+\item[\opt1:]
+(Must be used with \ics{makenoidxglossaries} in the preamble.)
+\begin{definition}[\DescribeMacro\printnoidxglossaries]
+\cs{printnoidxglossaries}
+\end{definition}
+which internally uses \cs{printnoidxglossary} for each glossary.
+
+\item[\optsand23:]
+(Must be used with \ics{makeglossaries} in the preamble.)
+\begin{definition}[\DescribeMacro\printglossaries]
+\cs{printglossaries}
+\end{definition}
+which internally uses \cs{printglossary} for each glossary.
+
+\item[\optsto46:] (\gls{glossaries-extra} only)
+\begin{definition}[\DescribeMacro\printunsrtglossaries]
+\cs{printunsrtglossaries}
+\end{definition}
+which internally uses \cs{printunsrtglossary} for each glossary.
+\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}). In the case of \opt4, no glossary
+will appear until you have used \gls{bib2gls}.
+
+\begin{important}
+While the external files are missing, \cs{printglossary} will just do
+\ics{null} for each missing glossary to assist dictionary style
+documents that just use \cs{glsaddall} without inserting any text.
+This use of \ics{null} ensures that all indexing information is
+written before the final page is shipped out. Once the external
+files are present \cs{null} will no longer be used. This can cause a
+spurious blank page on the first \LaTeX\ run before the glossary
+files have been created. Once these files are present, \cs{null}
+will no longer be used and so shouldn't cause interference for the
+final document.
+\end{important}
+
+\begin{xtr}
+If you use \gls{glossaries-extra}, it will insert a heading and boilerplate text when the
+external files are missing. See the
+\gls{glossaries-extra} manual for further details.
+\end{xtr}
+
+If the glossary still does not appear after you re-\LaTeX\ your
+document, check the \gls*{makeindex}, \gls*{xindy} or \gls*{bib2gls}
+log files, as applicable, 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.)
+
+\itempar{\optsto46:}
+\begin{definition}
+\ics*{printunsrtglossary}\oarg{options}
+\end{definition}
+(May be used with or without \gls{bib2gls}.)
+\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.)
+
+\begin{xtr}
+The \gls{glossaries-extra} package also provides
+\begin{definition}
+\ics*{printunsrtinnerglossary}\oarg{options}\marg{pre
+code}\marg{post code}
+\end{definition}
+which is designed for inner or nested glossaries. It allows many, but not all,
+of the options listed below. There's an example available in the gallery:
+\gallery{index.php?label=bib2gls-inner}{Inner or Nested Glossaries}.
+See the \gls{glossaries-extra} package for further details.
+\end{xtr}
+
+The following keys are available in \marg{options}:
+\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 \ics*{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.
+
+\item[{\xtrprintglosskey[\marg{label}]{label}}]
+This key is only available with \gls{glossaries-extra} and labels
+the glossary with \cs{label}\marg{label}. This is an alternative to
+the package option \pkgopt[autolabel]{numberedsection}
+
+\item[{\xtrprintglosskey[\marg{boolean}]{target}}] This boolean key is only
+available with \gls{glossaries-extra} and can be used to switch
+off the automatic hypertarget for each entry. (This refers to the
+target used by commands like \cs{gls} and \cs{glslink}.)
+
+This option is useful with \ics*{printunsrtglossary} as it allows
+the same list (or sub-list) of entries to be displayed multiple
+times without causing duplicate hypertarget names.
+
+\item[{\xtrprintglosskey[\marg{prefix}]{prefix}}]
+This key is only available with \gls{glossaries-extra} and provides
+another way of avoiding duplicate hypertarget names. In this case it uses a
+different prefix for those names. This locally redefines
+\ics{glolinkprefix} but note this will also affect the target for any entry
+referenced within the glossary with commands like \cs{gls},
+\cs{glslink} or \cs{glshypertarget}.
+
+\item[{\xtrprintglosskey[\marg{prefix}]{targetnameprefix}}]
+This key is only available with \gls{glossaries-extra}.
+This is similar to the \pkgoptfmt{prefix} option, but it alters the prefix of
+the hypertarget anchors without changing \ics{glslinkprefix} (so it
+won't change the hyperlinks for any entries referenced in the
+glossary).
+
+\item[{\xtrprintglosskey[\marg{boolean}]{groups}}]
+This boolean key is only available with \gls{glossaries-extra} and,
+if true, will attempt to perform group formation. See the
+\gls{glossaries-extra} manual for further details.
+
+\item[{\xtrprintglosskey[\marg{n}]{leveloffset}}]
+This key is only available with \ics*{printunsrtglossary}.
+It can be used to locally adjust the
+hierarchical level used by the glossary style. See the
+\gls{glossaries-extra} manual for further details.
+\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
+\gls{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}
+
+\begin{xtr}
+The \gls{glossaries-extra} package provides additional hooks that
+can be used to make other minor adjustments.
+\end{xtr}
+
+The letter group titles (which are displayed for styles like
+\glostyle{indexgroup}) can be changed either by redefining the
+corresponding \cs{\meta{group-label}groupname} commands, such as
+\ics{glssymbolsgroupname}, (see \sectionref{sec:fixednames}) or by
+using the \gls{glossaries-extra} commands \ics*{glsxtrsetgrouptitle}
+and \ics*{glsxtrlocalsetgrouptitle}. The \meta{group-label} is
+typically obtained by the \gls{indexingapp}.
+
+\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.)
+
+\begin{xtr}
+The \gls{glossaries-extra} package provides a starred version of
+this command that allows hyperlinks (since ignored glossaries can be
+useful with \gls{bib2gls}). There is also an analogous
+\ics*{provideignoredglossary} command.
+\end{xtr}
+
+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{https://texfaq.org/FAQ-fixnam}{How to
+change LaTeX’s \qt{fixed names}}.
+\end{important}
+
+\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}).
+
+This command essentially works like \cs{index} (provided by the
+\LaTeX\ kernel) in that it doesn't produce text but it does add a
+line with an associated location to the glossary file. In this case,
+the \qt{encap} (the page encapsulator information) is specified with
+the \gloskey{format} key. (See \sectionref{sec:encap}.)
+
+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{bib2gls}
+If you are using \gls{bib2gls} with \gls{glossaries-extra}, you
+can't use \cs{glsaddall}. Instead use the \optfmt{selection=all}
+resource option to select all entries in the given \filetype{bib} files.
+\end{bib2gls}
+
+\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 been \glsdisp{firstuseflag}{marked as used}:
+\begin{definition}[\DescribeMacro\glsaddallunused]
+\cs{glsaddallunused}\oarg{list}
+\end{definition}
+This command uses \cs{glsadd}\texttt{[format=glsignore]} which will
+ignore this location in the number list. (See \sectionref{sec:encap}.)
+The optional argument \meta{list} is a comma-separated list of
+glossary types. If omitted, it defaults to the list of all defined
+glossaries.
+
+\begin{important}
+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.
+\end{important}
+
+\begin{bib2gls}
+With \gls{glossaries-extra} and \gls{bib2gls}, \texttt{glsignore}
+indicates an \qt{ignored location} which influences selection but
+isn't added to the location list. In this case, if you use
+\optfmt{selection=all} then only those entries that have been
+explicitly indexed in the document will have location lists. The
+other entries that were selected as a result of
+\optfmt{selection=all} won't have location lists.
+\end{bib2gls}
+
+Base \sty{glossaries} package only:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\makeglossaries
+\newglossaryentry{cat}{name={cat},description={feline}}
+\newglossaryentry{dog}{name={dog},description={canine}}
+\begin{document}
+\gls{cat}.
+\printglossaries
+\glsaddallunused % <- make sure dog is also listed
+\end{document}
+\end{verbatim}
+Corresponding \gls{glossaries-extra} and \gls{bib2gls} document code:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[record]{glossaries-extra}
+\GlsXtrLoadResources[src={entries},selection=all]
+\begin{document}
+\gls{cat}.
+\printunsrtglossaries
+\end{document}
+\end{verbatim}
+With the file \texttt{entries.bib}:
+\begin{verbatim}
+@entry{cat,name={cat},description={feline}}
+@entry{dog,name={dog},description={canine}}
+\end{verbatim}
+
+\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}|.
+
+This is just an example.
+In general, think twice before you add this kind of duplication.
+If all information (short, long and description) can be provided in
+a single list, it's redundant to provide a second list unless any
+of the short forms start with a different letter to the associated
+long form, which may make it harder to lookup.
+
+\begin{bib2gls}
+Note that with \gls{bib2gls}, there are special dual entry types
+that implement this behaviour. That is, if an entry is referenced
+then its corresponding dual entry will automatically be selected as
+well. So there is less need for \cs{glsadd} with \gls{bib2gls}.
+(Although it can still be useful, as shown in \opt6.)
+\end{bib2gls}
+\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{prompt}
+pdflatex filename
+makeglossaries filename
+pdflatex filename
+makeglossaries filename
+pdflatex filename
+\end{prompt}
+This is because the \cs{gls} in the description won't be detected
+until the glossary has been created (unless the description is used
+elsewhere in the document with \ics{glsentrydesc}). Take care not to
+use \ics{glsdesc} (or \ics{Glsdesc}) in this case as it will cause a
+nested link.
+
+\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.
+
+\begin{bib2gls}
+\gls{bib2gls} provides much better support for cross-references.
+See, for example,
+\gallery{index.php?label=bib2gls-xr}{Gallery: Cross-References (bib2gls)}.
+\end{bib2gls}
+
+\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{xtr}
+The \gls{glossaries-extra} package redefines \cs{glsseeitemformat}
+and additionally provides \ics*{glsxtrhiername} which can be used
+as an alternative to \cs{glsentrytext}. See the
+\gls{glossaries-extra} manual for further details.
+\end{xtr}
+
+\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{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 (Location Formats)}
+\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:
+\begin{definition}[\glsignore]
+\cs{glsignore}\marg{text}
+\end{definition}
+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 would need to use
+\texttt{selection=all} instead of \cs{glsaddallunused}, but even if
+you explicitly had used \texttt{glsignore}, for example,
+\cs{gls}\texttt{[format=glsignore]}\marg{label}, then \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 indexing options.
+
+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
+\filetype{aux} file. The write operation is deferred to avoid the
+problems associated with \TeX's asynchronous output routine.
+(See, for example,
+\href{https://texfaq.org/FAQ-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
+\begin{alltt}
+\cs{glsaddprotectedpagefmt}\marg{internal cs name}
+\end{alltt}
+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 \xindyattr{: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|main} 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{Glossary Styles}
\label{sec:styles}
@@ -11867,7 +11708,7 @@ with a number of pre-defined glossary styles, described in
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 \gallerytopic{glossaries}.
+of glossary styles available at the \gallerytopic{glossaries}.
The glossary style can be set using the \gloskey[printglossary]{style} key in the optional
argument to \ics{printnoidxglossary} (\opt1) or \ics{printglossary}
@@ -11904,9 +11745,9 @@ of available styles in \tableref{tab:styles}.
You can view samples of all the predefined styles at
\galleryurl{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.
+in the supplementary packages \sty{glossary-bookindex},
+\sty{glossary-topic} and \sty{glossary-longextra}. See the
+\gls{glossaries-extra} manual for further details.
\begin{important}
Note that the group styles (such as \glostyle{listgroup}) will
@@ -12988,6 +12829,16 @@ This defaults to just \meta{description}.
\section{Defining your own glossary style}
\label{sec:newglossarystyle}
+\begin{important}
+Commands like \cs{printglossary} are designed to produce content in
+the PDF. If your intention is to design a style that doesn't print
+any content (for example, to simply capture information) then you
+are likely to experience unwanted side-effects. If you just want to
+capture indexing information (such as locations) then a much better
+approach is to use \gls{bib2gls}, which automatically stores this
+information in dedicated fields when the entry is defined.
+\end{important}
+
If the predefined styles don't fit your requirements, you can
define your own style using:
\begin{definition}[\DescribeMacro{\newglossarystyle}]
@@ -13332,6 +13183,565 @@ that displays each entry in a \env{longtable} as follows:
\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 \ixindyattrs 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 \ixindyattrs 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
+\ixindyattrs 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
+\gls{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{Utilities}
\label{sec:utilities}
@@ -13375,6 +13785,12 @@ 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{xtr}
+The \gls{glossaries-extra}
+package provides an analogous command
+\ics*{forallabbreviationlists}.
+\end{xtr}
+
\begin{definition}[\DescribeMacro{\forglsentries}]
\cs{forglsentries}\oarg{glossary label}\marg{cs}\marg{body}
\end{definition}
@@ -13474,7 +13890,14 @@ 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}.
+\meta{false part}. This uses an inefficient method since this
+information isn't stored.
+
+\begin{bib2gls}
+If you use \gls{bib2gls}, a more efficient method is to use the
+\resourceopt{save-child-count} resource option and test the value of
+the \field{childcount} field.
+\end{bib2gls}
\begin{definition}[\DescribeMacro{\ifglshasparent}]
\cs{ifglshasparent}{\meta{label}}{\meta{true part}}{\meta{false
@@ -14314,7 +14737,7 @@ The \gls{glossaries-extra} package and \gls{bib2gls}
provide some additional sample files. There are also examples in the
\gallery{}{Dickimaw Books Gallery}.
-If you prefer to use UTF-8 aware engines (\texttt{xelatex} or
+If you prefer to use \gls{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.
@@ -18272,7 +18695,7 @@ also the earlier \samplefile{Sec}.
\exitem{utf8} This is another example
that uses \gls{xindy}. Unlike \gls{makeindex},
\gls{xindy} can cope with \glspl{nonlatinchar}. This
-document uses UTF-8 encoding. To create the document do:
+document uses \gls{UTF-8} encoding. To create the document do:
\begin{prompt}
pdflatex sampleutf8
makeglossaries sampleutf8
@@ -19214,10 +19637,10 @@ 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}.
+\urlfootref{https://latex.org/forum/}{\LaTeX\ Community Forum} or
+\urlfootref{https://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}.
+\urlfootref{https://www.dickimaw-books.com/bug-report.html}{my package bug report form}.
\PrintIndex