summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex1967
1 files changed, 1429 insertions, 538 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
index d2680063891..33663add251 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -5,6 +5,8 @@
\usepackage{array}
\usepackage{alltt}
\usepackage{pifont}
+\usepackage{textcomp}
+\usepackage{amssymb}
\ifpdf
\usepackage{lmodern}
\usepackage{mathpazo}
@@ -18,6 +20,7 @@
\fi
\usepackage[colorlinks,
bookmarks,
+ linkcolor=blue,
hyperindex=false,
pdfauthor={Nicola L.C. Talbot},
pdftitle={User Manual for glossaries.sty},
@@ -122,7 +125,20 @@
name={\appfmt{makeindex}\index{makeindex=\appfmt{makeindex}|htextbf}},%
sort={makeindex},%
text={\appfmt{makeindex}\iapp{makeindex}},%
-description={An \gls{indexingapp}.},
+description={An \gls{indexingapp}.}
+}
+
+\newglossaryentry{bib2gls}{%
+name={\appfmt{bib2gls}\index{bib2gls=\appfmt{bib2gls}|htextbf}},%
+sort={bib2gls},%
+text={\appfmt{bib2gls}\iapp{bib2gls}},%
+description={An \gls{indexingapp} that combines two functions in
+one: (1) fetches entry definition from a \texttt{.bib} file
+based on information provided in the \texttt{.aux} file (similar
+to \appfmt{bibtex}); (2) hierarchically sorts and collates location
+lists (similar to \appfmt{makeindex} and \appfmt{xindy}).
+This application is designed for use with \styfmt{glossaries-extra}
+and can't be used with just the base \styfmt{glossaries} package.}
}
\newglossaryentry{makeglossaries}{%
@@ -131,18 +147,22 @@ sort={makeglossaries},%
text={\appfmt{makeglossaries}\iapp{makeglossaries}},%
description={A custom designed Perl script interface
to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries}
-package.}
+package. \TeX\ distributions on Windows convert the original
+\texttt{makeglossaries} script into an executable
+\texttt{makeglossaries.exe} for convenience.}
}
\newglossaryentry{makeglossaries-lite.lua}{%
-name={\appfmt{makeglossaries-lite.lua}\index{makeglossaries-lite.lua=\appfmt{makeglossaries-lite.lua}|htextbf}},%
-sort={makeglossaries-lite.lua},%
-text={\appfmt{makeglossaries-lite.lua}\iapp{makeglossaries-lite.lua}},%
+name={\appfmt{makeglossaries-lite}\index{makeglossaries-lite=\appfmt{makeglossaries-lite}|htextbf}},%
+sort={makeglossaries-lite},%
+text={\appfmt{makeglossaries-lite}\iapp{makeglossaries-lite}},%
description={A custom designed Lua script interface
to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries}
package. This is a cut-down alternative to the Perl
\appfmt{makeglossaries} script. If you have Perl installed, use the
-Perl script instead. Note that \TeX~Live creates a symbolic link
+Perl script instead. This script is actually distributed with the
+file name \texttt{makeglossaries-lite.lua}, but \TeX~Live
+(on Unix-like systems) creates a symbolic link
called \texttt{makeglossaries-lite} (without the \texttt{.lua}
extension) to the actual \texttt{makeglossaries-lite.lua} script.}
}
@@ -338,11 +358,38 @@ user2={sanitization\protect\iterm{sanitize}}%
\newcommand*{\yes}{\ding{52}}
\newcommand*{\no}{\ding{56}}
+\newcommand*{\proyes}{\textcolor{green}{\yes}}
+\newcommand*{\prono}{\textcolor{red}{\no}}
+
+\newcommand*{\conyes}{\textcolor{red}{\yes}}
+\newcommand*{\conno}{\textcolor{green}{\no}}
+
\makeatletter
+\newcommand{\fnsymmark}[1]{#1}
+\newcommand*{\fnsym}[1]{\textsuperscript{\fnsymmark{%
+ \ifcase#1\or \textasteriskcentered \or \textdagger
+ \or \textdaggerdbl \or \textsection
+ \or $\lozenge$ \or \textparagraph
+ \or \#\or {\fontfamily{cmr}\selectfont\textreferencemark}%
+ \or \shortstack{*\\[-1.5ex]*}%
+ \or $\star$
+ \or \ding{94}%
+ \else
+ \number#1
+ \fi
+}}}%
\newcommand*{\optionlabel}[1]{%
- \@glstarget{option#1}{}\textbf{Option~#1}}
+ \@glstarget{option#1}{Option~#1}}
\makeatother
+\newcounter{option}
+\newcommand{\optionsec}[2][\opttitle]{%
+ \def\opttitle{\appfmt{#2}}%
+ \refstepcounter{option}%
+ \pdfbookmark[2]{Option~\theoption\space (#2)}{option\theoption}%
+ \subsection*{\protect\optionlabel{\theoption} (#1)}%
+}
+
\newcommand*{\opt}[1]{\hyperlink{option#1}{Option~#1}}
\newcommand*{\optsor}[2]{Options~\hyperlink{option#1}{#1}
or~\hyperlink{option#2}{#2}}
@@ -371,6 +418,8 @@ and~\hyperlink{option#2}{#2}}
\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}}
\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}}
+\newcommand*{\optfmt}[1]{\textsf{#1}}
+\newcommand*{\field}[1]{\optfmt{#1}\index{internal fields:>#1=\protect\optfmt{#1}|main}}
\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\ttfamily#1}|main}}
@@ -398,11 +447,11 @@ and~\hyperlink{option#2}{#2}}
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for glossaries.sty v4.32}
+ \title{User Manual for glossaries.sty v4.33}
\author{Nicola L.C. Talbot\\%
\url{http://www.dickimaw-books.com/}}
- \date{2017-08-24}
+ \date{2017-09-20}
\maketitle
\begin{abstract}
@@ -415,17 +464,24 @@ Additional features not provided here may be available through
the supplemental package \gls{glossaries-extra} which, if required,
needs to be installed separately. New features will be added to
\gls*{glossaries-extra}. Versions of the \styfmt{glossaries}
-package after v4.21 will mostly be just bug fixes.
+package after v4.21 will mostly be just bug fixes. Note that
+\gls{glossaries-extra} provides an extra indexing option
+(\gls{bib2gls}) which isn't available with just the base
+\sty{glossaries} package.
\end{abstract}
If you require multilingual support you must also separately install
-the relevant language module. Each language module is called
-\texttt{glossaries-}\meta{language}, where \meta{language} is the
+the relevant language module. Each language module is distributed
+under the name \texttt{glossaries-}\meta{language}, where \meta{language} is the
root language name. For example, \texttt{glossaries-french}
or \texttt{glossaries-german}. If a language module is required,
the \styfmt{glossaries} package will automatically try to load it and
will give a warning if the module isn't found. See
\sectionref{sec:languages} for further details.
+If there isn't any support available for your language, use
+the \pkgopt{nolangwarn} package option to suppress the warning
+and provide your own translations. (For example, use
+the \gloskey[printglossary]{title} key in \cs{printglossary}.)
The \styfmt{glossaries} package requires a number of other packages
including, but not limited to, \sty{tracklang}, \sty{mfirstuc},
@@ -480,7 +536,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.32}.
+\qt{Documented Code for glossaries v4.33}.
\item[INSTALL] Installation instructions.
@@ -506,6 +562,8 @@ Nomenclature, Lists of Symbols and Acronyms}
\item The
\href{http://ctan.org/pkg/glossaries-extra}{\styfmt{glossaries-extra} package}
+
+\item \href{http://ctan.org/pkg/bib2gls}{\appfmt{bib2gls}}
\end{itemize}
\begin{important}
@@ -549,7 +607,7 @@ user to customize the format of the glossary and define multiple
glossaries. It also supports glossary styles that
include symbols (in addition to a name and description) for glossary
entries. There is provision for loading a database of glossary
-terms. Only those terms used\footnote{That is, if the term has been
+terms. Only those terms indexed\footnote{That is, if the term has been
referenced using any of the commands described in
\sectionref{sec:glslink} and \sectionref{sec:glsadd} or via
\ics{glssee} (or the \gloskey{see} key) or commands such as
@@ -573,69 +631,254 @@ a~requirement but it does increase the available options,
particularly if you use an \gls{exlatinalph} or a~\gls{nonlatinalph}.
\end{important}
+This document uses the \styfmt{glossaries} package. For example,
+when viewing the PDF version of this document in a
+hyperlinked-enabled PDF viewer (such as Adobe Reader or Okular) if
+you click on the word \qt{\gls{xindy}} you'll be taken to the entry
+in the glossary where there's a brief description of
+the term \qt{\gls*{xindy}}. This is the way the \styfmt{glossaries}
+mechanism works. An \gls{indexingapp} is used to generated the
+sorted list of terms. The \glspl{indexingapp} are \gls{cli} tools,
+which means they can be run directly from a command prompt or terminal, or can
+be integrated into some text editors, or you can use a build tool
+such as \app{arara} to run them.
+
+The remainder of this introductory section covers the following:
+\begin{itemize}
+\item \sectionref{sec:indexingoptions} lists the available indexing
+options.
+
+\item \sectionref{sec:samples} lists the sample documents provided
+with this package.
+
+\item \sectionref{sec:lipsum} lists the dummy glossary files that
+may be used for testing.
+
+\item \sectionref{sec:languages} provides information for users who
+wish to write in a language other than English.
+
+\item \sectionref{sec:makeglossaries} describes how to use an
+\gls{indexingapp} to create the sorted glossaries for your document
+(\optsor23).
+
+\end{itemize}
+
+\section{Indexing Options}
+\label{sec:indexingoptions}
+
The basic idea behind the \styfmt{glossaries} package is that you
first define your entries (terms, symbols or abbreviations). Then
you can reference these within your document (like \cs{cite} or
\cs{ref}). You can also, optionally, display a~list of the entries
you have referenced in your document (the glossary). This last part,
displaying the glossary, is the part that most new users find
-difficult. There are three options:
+difficult. There are three options available with the base
+\styfmt{glossaries} package and two further options with the
+extension package \gls{glossaries-extra}.
+An overview of these options is given in
+\tableref{tab:options}.
-\begin{description}
-\item[]\optionlabel1:
-
- This is the simplest option but it's slow and if
- you want a sorted list, it doesn't work well for \glspl{exlatinalph} or
- \glspl{nonlatinalph}. However, if you use the
- \pkgopt[false]{sanitizesort} package option (the default for
- Option~1) then the \glslink{latexexlatinchar}{standard \LaTeX\ accent commands} will be
- ignored, so if an entry's name is set to \verb|{\'e}lite| then the
- sort will default to \texttt{elite} if
- \pkgopt[false]{sanitizesort} is used
- and will default to \verb|\'elite| if \pkgopt[true]{sanitizesort}
- is used.
-
- This option works best with the \pkgopt[def]{sort} setting. For any
- other setting, be prepared for a long document build time,
- especially if you have a lot of entries defined. \textbf{This
-option is intended as a last resort for alphabetical sorting.}
-This option is not suitable for hierarchical glossaries.
+If you are developing a class or package that loads
+\styfmt{glossaries}, I recommend that you don't force the user into
+a particular indexing method by adding an unconditional \cs{makeglossaries}
+into your class or package code. Aside from forcing the user into a
+particular indexing method, it means that they're unable to use any
+commands that must come before \cs{makeglossaries} (such as
+\cs{newglossary}) and they can't switch off the indexing whilst
+working on a draft document.
- \begin{enumerate}
- \item Add \cs{makenoidxglossaries} to your preamble (before you
- start defining your entries, as described in
- \sectionref{sec:newglosentry}).
+\begin{table}[htbp]
+ \caption{Glossary Options: Pros and Cons}
+ \label{tab:options}
+ {%
+ \renewcommand{\fnsymmark}[1]{\rlap{#1}}%
+ \setlength{\tabcolsep}{3pt}%
+ \centering
+ \begin{tabular}{@{}>{\raggedright\small}p{0.35\textwidth}ccccc@{}}
+ & \bfseries \opt1 & \bfseries \opt2 & \bfseries \opt3
+ & \bfseries \opt4 & \bfseries \opt5\\
+ Requires \gls{glossaries-extra}? &
+ \conno & \conno & \conno & \conyes & \conyes\\
+ Requires an external application? &
+ \conno & \conyes & \conyes & \conyes & \conno\\
+ Requires Perl? &
+ \conno & \conno & \conyes & \conno & \conno\\
+ Requires Java? &
+ \conno & \conno & \conno & \conyes & \conno\\
+ Can sort \glspl{exlatinalph}
+ or \glspl{nonlatinalph}? &
+ \prono\fnsym{1} & \prono & \proyes & \proyes & N/A\\
+ Efficient sort algorithm? &
+ \prono & \proyes & \proyes & \proyes & N/A\\
+ Can use a different sort method for each glossary? &
+ \proyes
+ & \prono\fnsym{2}
+ & \prono\fnsym{2} & \proyes & N/A\\
+ Any problematic sort values? &
+ \conyes & \conyes & \conyes & \conno & \conno\fnsym{3}\\
+ Are entries with identical sort values treated as separate unique
+ entries? &
+ \proyes & \proyes & \prono\fnsym{4} & \proyes & \proyes\\
+ Can automatically form ranges in the location lists? &
+ \prono & \proyes & \proyes & \proyes & \prono\\
+ Can have non-standard locations in the location lists? &
+ \proyes & \prono
+ & \proyes\fnsym{5}
+ & \proyes
+ & \proyes\fnsym{6}\\
+ Maximum hierarchical depth (style-dependent) &
+ $\infty$\fnsym{7} & 3 & $\infty$ & $\infty$ & $\infty$\\
+ \ics{glsdisplaynumberlist} reliable? &
+ \proyes & \prono & \prono & \proyes & \prono\\
+ \ics{newglossaryentry} allowed in \env{document} environment?
+ (Not recommended.) &
+ \no & \yes & \yes & \no\fnsym{8} & \yes\fnsym{9}\\
+ Requires additional write registers? &
+ \conno & \conyes & \conyes & \conno & \conno\fnsym{10}\\
+ Default value of \pkgopt{sanitizesort} package option &
+ \texttt{false} & \texttt{true} & \texttt{true}
+ & \texttt{true}\fnsym{11}
+ & \texttt{true}\fnsym{11}
+ \end{tabular}
+ \par
+ }\par
+ \smallskip
+ \hrulefill\par
+ \smallskip\footnotesize
+ \fnsym{1} Strips standard \LaTeX\ accents
+(that is, accents generated by core \LaTeX\ commands) so,
+for example, \ics{AA} is treated the same as A.\par
+ \fnsym{2} Only with the hybrid method provided with \sty{glossaries-extra}.\par
+ \fnsym{3} Provided \pkgopt[none]{sort} is used.\par
+ \fnsym{4} Entries with the same sort value are merged.\par
+ \fnsym{5} Requires some setting up.\par
+ \fnsym{6} The locations must be set explicitly
+through the custom \field{location} field provided by
+\styfmt{glossaries-extra}.\par
+ \fnsym{7} Unlimited but unreliable.\par
+ \fnsym{8} Entries are defined in \texttt{.bib}
+format. \cs{newglossaryentry} should not be used explicitly.\par
+ \fnsym{9} Provided \pkgoptfmt{docdefs=true} or
+\pkgoptfmt{docdefs=restricted} but not recommended.\par
+ \fnsym{10} Provided \pkgoptfmt{docdefs=false} or
+\pkgoptfmt{docdefs=restricted}.\par
+ \fnsym{11} Irrelevant with \pkgopt[none]{sort}. (The \optfmt{record=only}
+ option automatically switches this on.)
+\par
+\end{table}
- \item Put
-\begin{definition}
-\cs{printnoidxglossary}
-\end{definition}
- where you want your list of entries to appear (described in
- \sectionref{sec:printglossary}).
- \item Run \LaTeX\ twice on your document. (As you would do to
- make a~table of contents appear.) For example, click twice on
- the \qt{typeset} or \qt{build} or \qt{PDF\LaTeX} button in your editor.
- \end{enumerate}
+\optionsec[\TeX]{TeX}
+
+This option doesn't require an external \gls{indexingapp} but, with
+the default alphabetic sorting, it's very slow with severe limitations.
+If you want a sorted list, it doesn't work well for
+\glspl{exlatinalph} or \glspl{nonlatinalph}. However, if you use
+the \pkgopt[false]{sanitizesort} package option (the default for
+Option~1) then the \glslink{latexexlatinchar}{standard \LaTeX\
+accent commands} will be ignored, so if an entry's name is set to
+\verb|{\'e}lite| then the sort will default to \texttt{elite} if
+\pkgopt[false]{sanitizesort} is used and will default to
+\verb|\'elite| if \pkgopt[true]{sanitizesort} is used. If you have
+any other kinds of commands that don't expand to ASCII characters,
+such as \cs{alpha} or \cs{si}, then you must use
+\pkgopt[true]{sanitizesort} or change the sort method
+(\pkgopt[use]{sort} or \pkgopt[def]{sort}) in the package options
+or explicitly set the \gloskey{sort} key when you define the
+relevant entries. For example:
+\begin{verbatim}
+\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
+ sort={alpha},description={...}}
+\end{verbatim}
+
+This option works best with the \pkgopt[def]{sort} or
+\pkgopt[use]{sort} setting. For any
+other setting, be prepared for a long document build time,
+especially if you have a lot of entries defined. \textbf{This
+option is intended as a last resort for alphabetical sorting.}
+This option allows a mixture of sort methods. (For example,
+sorting by word order for one glossary and order of use for another.)
+This option is not suitable for hierarchical glossaries and does
+not form ranges in the \glspl{numberlist}. If you really can't use an
+\gls{indexingapp} consider using \opt{5} instead.
-\item\optionlabel2:
+ \begin{enumerate}
+ \item Add
+\begin{verbatim}
+\makenoidxglossaries
+\end{verbatim}
+ to your preamble (before you start defining your entries, as described in
+ \sectionref{sec:newglosentry}).
- 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}, so
- it doesn't work well for \glspl{exlatinalph} or
- \glspl{nonlatinalph}. This process involves making \LaTeX\ write the
- glossary information to a temporary file which \gls{makeindex} reads.
- Then \gls{makeindex} writes a~new file containing the code to typeset
- the glossary. \LaTeX\ then reads this file in on the next run.
+ \item Put
+\begin{verbatim}
+\printnoidxglossary
+\end{verbatim}
+ where you want your list of entries to appear (described in
+ \sectionref{sec:printglossary}). Alternatively, to display all
+ glossaries use the iterative command:
+\begin{verbatim}
+\printnoidxglossaries
+\end{verbatim}
- This option works best if you want to sort entries according to the
- English alphabet and you don't want to install Perl.
+ \item Run \LaTeX\ twice on your document. (As you would do to
+ make a~table of contents appear.) For example, click twice on
+ the \qt{typeset} or \qt{build} or \qt{PDF\LaTeX} button in your editor.
+ \end{enumerate}
+
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\makenoidxglossaries % use TeX to sort
+\newglossaryentry{sample}{name={sample},
+ description={an example}}
+\begin{document}
+\gls{sample}.
+\printnoidxglossary
+\end{document}
+\end{verbatim}
+
+\optionsec{makeindex}
+
+This option uses a~\gls{cli} application called \gls{makeindex} to sort
+the entries. This application comes with all modern \TeX\ distributions,
+but it's hard-coded for the non-extended \gls{latinalph}. It can't
+correctly sort accent commands (such as \cs{'} or \cs{c}) and fails
+with UTF-8 characters, especially for any sort values that start
+with a UTF-8 character (as it separates the octets resulting in an
+invalid file encoding). This process involves making \LaTeX\ write
+the glossary information to a temporary file which \gls{makeindex}
+reads. Then \gls{makeindex} writes a~new file containing the code
+to typeset the glossary. Then \cs{printglossary} reads this file in
+on the next run.
+
+This option works best if you want to sort entries according to the
+English alphabet and you don't want to install Perl (or Java or
+you don't want to use \gls{glossaries-extra}). This method can
+also work with the restricted shell escape since \gls{makeindex}
+is considered a trusted application. (So you should be able to
+use the \pkgopt{automake} package option provided the shell
+escape hasn't been completely disabled.)
+
+This method can form ranges in the \gls{numberlist} but only
+accepts limited number formats: \cs{arabic}, \cs{roman},
+\cs{Roman}, \cs{alph} and \cs{Alph}.
+
+This option does not allow a mixture of sort methods.
+All glossaries must be sorted according to the same method:
+word\slash letter ordering or order of use or order of definition.
+If you need word ordering for one glossary and letter ordering
+for another you'll have to explicitly call \gls{makeindex} for
+each glossary type.
+(The \sty{glossaries-extra} package allows a hybrid mix of
+\optsand12 to provide word\slash letter ordering with \opt2 and order
+of use\slash definition with \opt1. See the \sty{glossaries-extra}
+documentation for further details.)
\begin{enumerate}
\item If you want to use \gls{makeindex}['s] \mkidxopt{g} option
- you must change the quote character using \ics{GlsSetQuote}. For
-example:
+ you must change the quote character using \ics{GlsSetQuote}. For example:
\begin{verbatim}
\GlsSetQuote{+}
\end{verbatim}
@@ -644,23 +887,33 @@ example:
enabled until the start of the document, so you won't be able to use
the shorthands in definitions made in the preamble.
- \item Add \cs{makeglossaries} to your preamble (before you start
+ \item Add
+\begin{verbatim}
+\makeglossaries
+\end{verbatim}
+to your preamble (before you start
defining your entries, as described in
\sectionref{sec:newglosentry}).
\item Put
-\begin{definition}
-\cs{printglossary}
-\end{definition}
+\begin{verbatim}
+\printglossary
+\end{verbatim}
where you want your list of entries to appear (described in
- \sectionref{sec:printglossary}).
+ \sectionref{sec:printglossary}). Alternatively, to display all
+ glossaries use the iterative command:
+\begin{verbatim}
+\printglossaries
+\end{verbatim}
\item Run \LaTeX\ on your document. This creates files with the
extensions \texttt{.glo} and \texttt{.ist} (for example, if your
\LaTeX\ document is called \texttt{myDoc.tex}, then you'll have
two extra files called \texttt{myDoc.glo} and \texttt{myDoc.ist}).
If you look at your document at this point, you won't see the
- glossary as it hasn't been created yet.
+ glossary as it hasn't been created yet. (If you use
+ \sty{glossaries-extra} you'll see the section heading and some
+ boilerplate text.)
\item Run \gls{makeindex} with the \texttt{.glo} file as the
input file and the \texttt{.ist} file as the style so that
@@ -672,53 +925,113 @@ example:
makeindex -s myDoc.ist -o myDoc.gls myDoc.glo
\end{verbatim}
(Replace \texttt{myDoc} with the base name of your \LaTeX\
- document file. Avoid spaces in the file name.) If you don't know
+ document file. Avoid spaces in the file name if possible.) If you don't know
how to use the command prompt, then you can probably access
\gls{makeindex} via your text editor, but each editor has a
different method of doing this, so I~can't give a~general
- description. You will have to check your editor's manual.
+ description. You will have to check your editor's manual. The
+ simplest approach is to use \app{arara} and add the following
+ comment lines to the start of your document:
+\begin{alltt}
+\% arara:\ pdflatex
+\% arara:\ makeglossaries
+\% arara:\ pdflatex
+\end{alltt}
+ (Replace \texttt{makeglossaries} with
+ \texttt{makeglossaries-lite} if you don't have Perl installed.)
- The default sort is word order (\qt{sea lion} comes before
-\qt{seal}).
+ The default sort is word order (\qt{sea lion} comes before \qt{seal}).
If you want letter ordering you need to add the \mkidxopt{l}
switch:
\begin{verbatim}
makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo
\end{verbatim}
(See \sectionref{sec:makeindexapp} for further details on using
- \gls*{makeindex} explicitly.)
+ \gls*{makeindex} explicitly.) If you use \gls{makeglossaries}
+ or \gls{makeglossaries-lite.lua} then use the \pkgopt[letter]{order}
+ package option and the \mkidxopt{l} option will be added
+ automatically.
\item Once you have successfully completed the previous step,
- you can now run \LaTeX\ on your document again.
+ you can now run \LaTeX\ on your document again. You'll need to
+ repeat the process if you have used the \pkgopt{toc} option
+ (unless you're using \sty{glossaries-extra}) to ensure the
+ section heading is added to the table of contents. You'll also
+ need to repeat the process if you have any cross-references
+ which can't be indexed until the glossary file has been created.
\end{enumerate}
- This is the default option (although you still need to use
- \cs{makeglossaries} to ensure the glossary files are created).
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\makeglossaries % open glossary files
+\newglossaryentry{sample}{name={sample},
+ description={an example}}
+\begin{document}
+\gls{sample}.
+\printglossary
+\end{document}
+\end{verbatim}
-\item\optionlabel3:
+\optionsec{xindy}
- This option uses a~\gls{cli} application called
- \gls{xindy} to sort the entries. This application is more flexible than
- \texttt{makeindex} and is able to sort \glspl{exlatinalph} or
- \glspl{nonlatinalph}. The \gls{xindy} application comes with \TeX~Live
- and now also with MiK\TeX. Since \gls{xindy} is a Perl script, you
- will also need to install Perl, if you don't already have it.
- In a~similar way to \opt2, this
- option involves making \LaTeX\ write the glossary information to
- a~temporary file which \gls{xindy} reads. Then \gls{xindy}
- writes a~new file containing the code to typeset the glossary.
- \LaTeX\ then reads this file in on the next run.
+This option uses a~\gls{cli} application called
+\gls{xindy} to sort the entries. This application is more flexible than
+\texttt{makeindex} and is able to sort \glspl{exlatinalph} or
+\glspl{nonlatinalph}, however it does still have some limitations.
- This is the best option if you want to sort according to a
- language other than English or if you want non-standard location
- lists.
+The \gls{xindy} application comes with both \TeX~Live and
+MiK\TeX, but since \gls{xindy} is a Perl script, you will also need
+to install Perl, if you don't already have it. In a~similar way to
+\opt2, this option involves making \LaTeX\ write the glossary
+information to a~temporary file which \gls{xindy} reads. Then
+\gls{xindy} writes a~new file containing the code to typeset the
+glossary. Then \cs{printglossary} reads this file in on the next run.
- \begin{enumerate}
+This is the best option with just the base \styfmt{glossaries}
+package if you want to sort according to a~language other than
+English or if you want non-standard location lists, but it can
+require some setting up (see \sectionref{sec:xindy}). There are
+some problems with certain sort values:
+\begin{itemize}
+ \item entries with the same sort value are merged by \gls*{xindy}
+ into a single glossary line so you must make sure that each entry
+ has a unique sort value;
+ \item \gls*{xindy} forbids empty sort values;
+ \item \gls*{xindy} automatically strips control sequences, the math-shift
+ character \verb|$| and braces \verb|{}| from the sort value,
+ which is usually desired but this can cause the sort value to
+ collapse to an empty string which \gls*{xindy} forbids.
+\end{itemize}
+In these problematic cases, you must set the \gloskey{sort} field
+explicitly. For example:
+\begin{verbatim}
+\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
+ sort={alpha},description={...}}
+\end{verbatim}
+
+All glossaries must be sorted according to the same method
+(word/letter ordering, order of use, or order of definition).
+(The \sty{glossaries-extra} package allows a hybrid mix of
+\optsand13 to provide word\slash letter ordering with \opt3 and order
+of use\slash definition with \opt1. See the \sty{glossaries-extra}
+documentation for further details.)
+
+\begin{enumerate}
\item Add the \pkgopt{xindy} option to the \styfmt{glossaries}
package option list:
\begin{verbatim}
\usepackage[xindy]{glossaries}
\end{verbatim}
+ If you are using a non-Latin script you'll also need to either
+ switch off the creation of the number group:
+\begin{verbatim}
+\usepackage[xindy={glsnumbers=false}]{glossaries}
+\end{verbatim}
+ or use either \cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter} or
+ \cs{GlsSetXdyNumberGroupOrder}\marg{spec} to indicate where the number
+ group should be placed (see \sectionref{sec:xindy}).
\item Add \cs{makeglossaries} to your preamble (before you start
defining your entries, as described in \sectionref{sec:newglosentry}).
@@ -728,7 +1041,9 @@ package option list:
\LaTeX\ document is called \texttt{myDoc.tex}, then you'll have
two extra files called \texttt{myDoc.glo} and \texttt{myDoc.xdy}).
If you look at your document at this point, you won't see the
- glossary as it hasn't been created yet.
+ glossary as it hasn't been created yet. (If you're using the
+ extension package \sty{glossaries-extra}, you'll see the section
+ header and some boilerplate text.)
\item Run \gls{xindy} with the \texttt{.glo} file as the
input file and the \texttt{.xdy} file as a~module so that
@@ -746,135 +1061,209 @@ xindy -L english -C utf8 -I xindy -M myDoc
document file. Avoid spaces in the file name. If necessary, also replace
\texttt{english} with the name of your language and \texttt{utf8}
with your input encoding, for example,
- \xdyopt{L}\texttt{ german }\xdyopt{C}\texttt{ din5007-utf8}.) If you don't know
- how to use the command prompt, then you can probably access
- \gls{xindy} via your text editor, but each editor has a
- different method of doing this, so I~can't give a~general
- description. You will have to check your editor's manual.
+ \xdyopt{L}\texttt{ german }\xdyopt{C}\texttt{ din5007-utf8}.)
+ Note that it's much simpler to use \gls{makeglossaries} instead:
+\begin{verbatim}
+makeglossaries myDoc
+\end{verbatim}
+ (Remember that \gls{xindy} is a Perl script so if you can use
+ \gls{xindy} then you can also use \gls{makeglossaries}, and if
+ you don't want to use \gls{makeglossaries} because you don't
+ want to install Perl, then you can't use \gls{xindy} either.)
+
+ If you don't know how to use the command prompt, then you can
+ probably access \gls{xindy} or \gls{makeglossaries} via your text editor,
+ but each editor has a different method of doing this, so I~can't give
+ a~general description. You will have to check your editor's manual. Again,
+ a convenient method is to use \appfmt{arara} and add the follow comment
+ lines to the start of your document:
+\begin{alltt}
+\% arara:\ pdflatex
+\% arara:\ makeglossaries
+\% arara:\ pdflatex
+\end{alltt}
- The default sort is word order (\qt{sea lion} comes before
-\qt{seal}).
+ The default sort is word order (\qt{sea lion} comes before \qt{seal}).
If you want letter ordering you need to add the
\pkgopt[letter]{order} package option:
\begin{verbatim}
\usepackage[xindy,order=letter]{glossaries}
\end{verbatim}
- (and return to the previous step.)
+ (and return to the previous step). This option is picked up
+ by \gls{makeglossaries}. If you are explicitly using \gls{xindy}
+ then you'll need to add \texttt{-M ord/letorder} to the options list.
See \sectionref{sec:xindyapp} for further details on using
\gls*{xindy} explicitly.
\item Once you have successfully completed the previous step,
- you can now run \LaTeX\ on your document again.
+ you can now run \LaTeX\ on your document again. As with the
+ previous option, you may need to repeat the process to ensure
+ the table of contents and cross-references are resolved.
- \end{enumerate}
+\end{enumerate}
-\end{description}
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[xindy]{glossaries}
+\makeglossaries % open glossary files
+\newglossaryentry{sample}{name={sample},
+ description={an example}}
+\begin{document}
+\gls{sample}.
+\printglossary
+\end{document}
+\end{verbatim}
-There is a fourth option available if you use the extension package
-\sty{glossaries-extra} (as from v1.08). See the \pkgoptfmt{record}
-package option in the \sty{glossaries-extra} user manual for
-further details.
+\optionsec{bib2gls}
-For \optsand23, it can be difficult to remember all the
-parameters required for \gls{makeindex} or \gls{xindy}, so the
-\styfmt{glossaries} package provides a~Perl script called
-\gls{makeglossaries} that reads the \texttt{.aux} file to
-determine what settings you have used and will then run
-\gls{makeindex} or \gls{xindy}. Again, this is a~command line
-application and can be run in a~terminal or command prompt. For
-example, if your \LaTeX\ document is in the file \texttt{myDoc.tex},
-then run:
+This option is only available with the extension package
+\gls{glossaries-extra}. This method uses \gls{bib2gls} to both
+fetch entry definitions from \texttt{.bib} files and to
+hierarchically sort and collate.
+
+All entries must be provided in one or more \texttt{.bib} files.
+(See the \gls{bib2gls} user manual for the required format.) The
+\sty{glossaries-extra} package needs to be loaded with the
+\pkgoptfmt{record} package option
\begin{verbatim}
-makeglossaries myDoc
+\usepackage[record]{glossaries-extra}
+\end{verbatim}
+or (equivalently)
+\begin{verbatim}
+\usepackage[record=only]{glossaries-extra}
\end{verbatim}
-(Replace \texttt{myDoc} with the base name of your \LaTeX\ document
-file. Avoid spaces in the file name.) This is described in more
-detail in \sectionref{sec:makeglossaries}.
+(It's possible to use a hybrid of this method and \optsor23 with
+\pkgoptfmt{record=alsoindex} but in general there is little need
+for this and it complicates the build process.)
-If you don't have Perl installed you can use the Lua script instead:
+Each resource set is loaded with \cs{GlsXtrLoadResources}\oarg{options}.
+For example:
\begin{verbatim}
-makeglossaries-lite.lua myDoc
+\GlsXtrLoadResources
+[% definitions in entries1.bib and entries2.bib:
+ src={entries1,entries2},
+ sort={de-CH-1996}% sort according to this locale
+]
\end{verbatim}
-This script doesn't have the full functionality of the Perl script,
-but since modern \TeX\ distributions come with Lua, you shouldn't
-need to install anything extra to make it run. Remember that since
-\gls{xindy} is also a~Perl script, if you want to use \gls{xindy}
-you'll need Perl installed anyway, so there's no point using this
-Lua script if you're using \gls{xindy}. Note that \TeX~Live creates a
-symbolic link called \texttt{makeglossaries-lite} (without the
-\texttt{.lua} extension) to the actual
-\texttt{makeglossaries-lite.lua} script, so you may not need to
-supply the extension.
+You can have multiple resource commands.
-\begin{important}
-The \texttt{.gls} and \texttt{.glo} are temporary files
-created to help build your document. You should not edit or explicitly input
-them. However, you may need to delete them if something goes wrong
-and you need to do a fresh build.
-\end{important}
+The glossary is displayed using
+\begin{verbatim}
+\printunsrtglossary
+\end{verbatim}
+Alternatively all glossaries can be displayed using the iterative
+command:
+\begin{verbatim}
+\printunsrtglossaries
+\end{verbatim}
+The document is build using:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls myDoc
+pdflatex myDoc
+\end{verbatim}
+If letter groups are required, you need the \verb|--group| switch:
+\begin{verbatim}
+bib2gls --group myDoc
+\end{verbatim}
+Unlike \optsand23, this method doesn't create a file containing
+the typeset glossary but simply determines which entries are
+needed for the document, their associated locations and (if
+required) their associated letter group. This option allows
+a mixture of sort methods. (For example, sorting by word order
+for one glossary and order of use for another or even sorting
+one block of the glossary differently to another block in the
+same glossary.)
-An overview of these three options is given in
-\tableref{tab:options}.
+This method supports Unicode and (with at least Java~8) uses
+the Common Locale Data Repository, which provides more extensive
+language support than \gls{xindy}.\footnote{Except for Klingon,
+which is supported by \gls{xindy}, but not by the
+CLDR.}\ The locations in the
+\gls{numberlist} may be in any format. If \gls{bib2gls} can
+deduce a numerical value it will attempt to form ranges otherwise
+it will simply list the locations.
-\begin{table}[htbp]
- \caption{Glossary Options: Pros and Cons}
- \label{tab:options}
- {%
- \centering
- \begin{tabular}{>{\raggedright}p{0.35\textwidth}ccc}
- & \bfseries \opt1 & \bfseries \opt2 & \bfseries \opt3\\
- Requires an external application? &
- \no & \yes & \yes\\
- Requires Perl? &
- \no & \no & \yes\\
- Can sort \glspl{exlatinalph}
- or \glspl{nonlatinalph}? &
- \no\textsuperscript{\textdagger} & \no & \yes\\
- Efficient sort algorithm? &
- \no & \yes & \yes\\
- Can use a different sort method for each glossary? &
- \yes & \no & \no\\
- Can form ranges in the location lists? &
- \no & \yes & \yes\\
- Can have non-standard locations in the location lists? &
- \yes & \no & \yes\\
- Maximum hierarchical depth &
- Unlimited but unreliable & 3 & Unlimited\\
- \ics{glsdisplaynumberlist} reliable? &
- \yes & \no & \no\\
- \ics{newglossaryentry} restricted to preamble? &
- \yes & \no & \no\\
- Requires additional write registers? &
- \no & \yes & \yes\\
- Default value of \pkgopt{sanitizesort} package option &
- \texttt{false} & \texttt{true} & \texttt{true}
- \end{tabular}
- \par
- }\textsuperscript{\textdagger} Strips standard \LaTeX\ accents
-(that is, accents generated by core \LaTeX\ commands) so,
-for example, \ics{AA} is treated the same as A.
-\end{table}
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[record]{glossaries-extra}
+\GlsXtrLoadResources[src={entries}]
+\begin{document}
+\gls{sample}.
+\printunsrtglossary
+\end{document}
+\end{verbatim}
+where \texttt{entries.bib} contains
+\begin{verbatim}
+@entry{sample,
+ name={sample},
+ description={an example}
+}
+\end{verbatim}
+See the \gls{bib2gls} user manual for further details.
-This document uses the \styfmt{glossaries} package. For example,
-when viewing the PDF version of this document in a
-hyperlinked-enabled PDF viewer (such as Adobe Reader or Okular) if
-you click on the word \qt{\gls{xindy}} you'll be taken to the entry
-in the glossary where there's a brief description of
-the term \qt{\gls*{xindy}}.
+\optionsec[no sorting]{no sorting}
-The remainder of this introductory section covers the following:
-\begin{itemize}
-\item \sectionref{sec:samples} lists the sample documents provided
-with this package.
+This option is only available with the extension package
+\gls{glossaries-extra}. No \gls{indexingapp} is required. This
+method is best used with the package option \pkgopt[none]{sort}.
+\begin{verbatim}
+\usepackage[sort=none]{glossaries-extra}
+\end{verbatim}
+There's no \qt{activation} command (such as \cs{makeglossaries}
+for \optsand23).
-\item \sectionref{sec:languages} provides information for users who
-wish to write in a language other than English.
+All entries must be defined before the glossary is displayed
+(preferably in the preamble) in the required order, and child
+entries must be defined immediately after their parent entry
+if they must be kept together in the glossary
-\item \sectionref{sec:makeglossaries} describes how to use an
-\gls{indexingapp} to create the sorted glossaries for your document
-(\optsor23).
+The glossary is displayed using
+\begin{verbatim}
+\printunsrtglossary
+\end{verbatim}
+Alternatively all glossaries can be displayed using the iterative
+command:
+\begin{verbatim}
+\printunsrtglossaries
+\end{verbatim}
+This will display \emph{all} defined entries, regardless of
+whether or not they have been used in the document. The
+\glspl{numberlist} have to be set explicitly otherwise they won't
+appear. Note that this uses the same command for displaying the
+glossary as \opt4. This is because \gls{bib2gls} takes advantage
+of this method by defining the wanted entries in the required order and
+setting the locations (and letter group information, if required).
-\end{itemize}
+This just requires a single \LaTeX\ call
+\begin{verbatim}
+pdflatex myDoc
+\end{verbatim}
+unless the glossary needs to appear in the table of contents, in which case
+a second run is required.
+\begin{verbatim}
+pdflatex myDoc
+pdflatex myDoc
+\end{verbatim}
+(Naturally if the document also contains citations, and so on,
+then additional steps are required. Similarly for all the other
+options above.)
+
+Complete example:
+\begin{verbatim}
+\documentclass{article}
+\usepackage[sort=none]{glossaries-extra}
+\newglossaryentry{sample}{name={sample},
+ description={an example}}
+\begin{document}
+\gls{sample}.
+\printunsrtglossary
+\end{document}
+\end{verbatim}
+See the \sty{glossaries-extra} documentation for
+further details.
\section{Sample Documents}
\label{sec:samples}
@@ -891,15 +1280,22 @@ For example, in a
texdoc -l glossaries
\end{prompt}
This should display a list of all the files in the glossaries
-documentation directory with their full pathnames.
+documentation directory with their full pathnames. (The GUI version
+of \texttt{texdoc} may also provide you with the information.)
If you can't find the sample files on your computer, they are also available
from your nearest CTAN mirror at
\url{http://mirror.ctan.org/macros/latex/contrib/glossaries/samples/}.
-The sample documents are as follows\footnote{Note that although I've written
+The sample documents are listed below\footnote{Note that although I've written
\texttt{latex} in this section, it's better to use \texttt{pdflatex}, where
-possible, for the reasons given \hyperlink{pdflatexnote}{earlier}.}:
+possible, for the reasons given \hyperlink{pdflatexnote}{earlier}.}
+If you prefer to use UTF-8 aware engines (\texttt{xelatex} or
+\texttt{lualatex}) remember that you'll need to switch from
+\styfmt{fontenc} \& \styfmt{inputenc} to \styfmt{fontspec} where
+appropriate. The \gls{glossaries-extra} package provides some
+additional sample files.
+
\begin{samplelist}
\exitem[minimal]{gls} This document is a
minimal working example. You can test your installation using this
@@ -929,18 +1325,16 @@ replaced by a fixed one
If this is the case, you will need to update the \styfmt{xkeyval}
package.
- \item Run \gls{makeglossaries} on the document (\sectionref{sec:makeglossaries}). This can
- be done on a terminal either by typing
+ \item If you have Perl installed, run \gls{makeglossaries} on the document (\sectionref{sec:makeglossaries}). This can
+ be done on a terminal by typing
\begin{prompt}
makeglossaries minimalgls
\end{prompt}
- or by typing
+ otherwise do
\begin{prompt}
-perl makeglossaries minimalgls
+makeglossaries-lite minimalgls
\end{prompt}
- If your system doesn't recognise the command \texttt{perl} then
- it's likely you don't have Perl installed. In which case you
- will need to use \gls{makeindex} directly. You can do this
+ If for some reason you want to call \gls{makeindex} explicitly, you can do this
in a terminal by typing (all on one line):
\begin{prompt}
makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls minimalgls.glo
@@ -948,9 +1342,8 @@ makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls minimalgls.glo
(See \sectionref{sec:makeindexapp} for further details on using
\gls*{makeindex} explicitly.)
- Note that if you need to specify the full path and the path
- contains spaces, you will need to delimit the file names with
- the double-quote character.
+ Note that if the file name contains spaces, you will need to use
+ the double-quote character to delimit the name.
\item Run \texttt{minimalgls.tex} through \LaTeX\ again (as step~1)
\end{enumerate}
@@ -988,14 +1381,18 @@ latex sample4col
makeglossaries sample4col
latex sample4col
\end{prompt}
-As before, if you don't have Perl installed, you will need to use
-\gls{makeindex} directly instead of using
-\gls{makeglossaries}. The vertical gap between entries is the
+or
+\begin{prompt}
+latex sample4col
+makeglossaries-lite sample4col
+latex sample4col
+\end{prompt}
+The vertical gap between entries is the
gap created at the start of each group. This can be suppressed
using the \pkgopt{nogroupskip} package option.
\exitem{Acr} This document has some
-sample acronyms. It also adds the glossary to the table of contents,
+sample abbreviations. It also adds the glossary to the table of contents,
so an extra run through \LaTeX\ is required to ensure the document
is up to date:
\begin{prompt}
@@ -1004,9 +1401,10 @@ makeglossaries sampleAcr
latex sampleAcr
latex sampleAcr
\end{prompt}
+(or use \gls{makeglossaries-lite.lua}).
\exitem{AcrDesc} This is similar to
-the previous example, except that the acronyms have an associated
+the previous example, except that the abbreviations have an associated
description. As with the previous example, the glossary is added to
the table of contents, so an extra run through \LaTeX\ is required:
\begin{prompt}
@@ -1017,7 +1415,7 @@ latex sampleAcrDesc
\end{prompt}
\exitem{Desc} This is similar to the
-previous example, except that it defines the acronyms using
+previous example, except that it defines the abbreviations using
\ics{newglossaryentry} instead of \ics{newacronym}. As with the
previous example, the glossary is added to the table of contents, so
an extra run through \LaTeX\ is required:
@@ -1028,7 +1426,7 @@ latex sampleDesc
latex sampleDesc
\end{prompt}
-\exitem{CustomAcr} This document has some sample acronyms with a
+\exitem{CustomAcr} This document has some sample abbreviations with a
custom acronym style. It also adds the glossary to the table of
contents, so an extra run through \LaTeX\ is required:
\begin{prompt}
@@ -1095,19 +1493,29 @@ latex sampleDB
makeglossaries sampleDB
latex sampleDB
\end{prompt}
+or
+\begin{prompt}
+latex sampleDB
+makeglossaries-lite sampleDB
+latex sampleDB
+\end{prompt}
The glossary definitions are stored in the accompanying files
-\texttt{database1.tex} and \texttt{database2.tex}. Note that if you
-don't have Perl installed, you will need to use \gls{makeindex}
-twice instead of a single call to \gls{makeglossaries}:
+\texttt{database1.tex} and \texttt{database2.tex}. If for some
+reason you want to call \gls{makeindex} explicitly you must
+have a separate call for each glossary:
\begin{enumerate}
\item Create the main glossary (all on one line):
-\begin{prompt}
+\begin{prompt}\raggedright
makeindex -s sampleDB.ist -t sampleDB.glg -o sampleDB.gls sampleDB.glo
\end{prompt}
\item Create the secondary glossary (all on one line):
-\begin{prompt}
+\begin{prompt}\raggedright
makeindex -s sampleDB.ist -t sampleDB.nlg -o sampleDB.not sampleDB.ntn
\end{prompt}
+Note that both \gls{makeglossaries} and \gls{makeglossaries-lite.lua} do
+this all in one call, so they not only make it easier because you
+don't need to supply all the switches and remember all the
+extensions but they also call \gls{makeindex} the appropriate number of times.
\end{enumerate}
\exitem{Eq} This document illustrates how
@@ -1155,16 +1563,16 @@ makeglossaries sampleNtn
latex sampleNtn
latex sampleNtn
\end{prompt}
-Note that if you don't have Perl installed, you will need to use
-\gls{makeindex} twice instead of a single call to
-\gls{makeglossaries}:
+Note that if you want to call \gls{makeindex} explicitly instead of
+using \gls{makeglossaries} or \gls{makeglossaries-lite.lua} then you
+need to call \gls{makeindex} twice:
\begin{enumerate}
\item Create the main glossary (all on one line):
-\begin{prompt}
+\begin{prompt}\raggedright
makeindex -s sampleNtn.ist -t sampleNtn.glg -o sampleNtn.gls sampleNtn.glo
\end{prompt}
\item Create the secondary glossary (all on one line):
-\begin{prompt}
+\begin{prompt}\raggedright
makeindex -s sampleNtn.ist -t sampleNtn.nlg -o sampleNtn.not sampleNtn.ntn
\end{prompt}
\end{enumerate}
@@ -1183,9 +1591,9 @@ latex sample
You can see the difference between word and letter ordering if you
substitute \pkgopt[word]{order} with \pkgopt[letter]{order}. (Note
that this will only have an effect if you use
-\gls{makeglossaries}. If you use \gls{makeindex} explicitly,
-you will need to use the \mkidxopt{l} switch to indicate letter
-ordering.)
+\gls{makeglossaries} or \gls{makeglossaries-lite.lua}.
+If you use \gls{makeindex} explicitly, you will need to use the
+\mkidxopt{l} switch to indicate letter ordering.)
\exitem{-inline} This document is
like \texttt{sample.tex}, above, but uses the \glostyle{inline}
@@ -1234,7 +1642,8 @@ uncomment the lines
\end{verbatim}
it will set the style file to \texttt{samplexdy-mc.xdy} instead.
This provides an additional letter group for entries starting with
-\qt{Mc} or \qt{Mac}. If you use \gls{makeglossaries}, you don't
+\qt{Mc} or \qt{Mac}. If you use \gls{makeglossaries} or
+\gls{makeglossaries-lite.lua}, you don't
need to supply any additional information. If you don't use
\gls*{makeglossaries}, you will need to specify the required
information. Note that if you set the style file to
@@ -1249,18 +1658,23 @@ latex samplexdy
makeglossaries samplexdy
latex samplexdy
\end{prompt}
-If you don't have Perl installed, you will have to call
-\gls{xindy} explicitly instead of using \gls{makeglossaries}.
-If you are using the default style file \texttt{samplexdy.xdy}, then
+If you don't have Perl installed then you can't use
+\gls{makeglossaries}, but you also can't use \gls{xindy}!
+However, if for some reason you want to call
+\gls{xindy} explicitly instead of using \gls{makeglossaries} (or
+\gls{makeglossaries-lite.lua}):
+\begin{itemize}
+\item if you are using the default style file \texttt{samplexdy.xdy}, then
do (no line breaks):
-\begin{prompt}
+\begin{prompt}\raggedright
xindy -L english -C utf8 -I xindy -M samplexdy -t samplexdy.glg -o samplexdy.gls samplexdy.glo
\end{prompt}
-otherwise, if you are using \texttt{samplexdy-mc.xdy}, then do
+\item if you are using \texttt{samplexdy-mc.xdy}, then do
(no line breaks):
-\begin{prompt}
+\begin{prompt}\raggedright
xindy -I xindy -M samplexdy-mc -t samplexdy.glg -o samplexdy.gls samplexdy.glo
\end{prompt}
+\end{itemize}
\exitem{xdy2} This document illustrates
how to use the \styfmt{glossaries} package where the location
@@ -1271,13 +1685,17 @@ pdflatex samplexdy2
makeglossaries samplexdy2
pdflatex samplexdy2
\end{prompt}
-If you can't use \gls{makeglossaries} then you need to do (all on
-one line):
-\begin{prompt}
+The explicit \gls{xindy} call is:
+\begin{prompt}\raggedright
xindy -L english -C utf8 -I xindy -M samplexdy2 -t samplexdy2.glg -o samplexdy2.gls samplexdy2.glo
\end{prompt}
See \sectionref{sec:xindyloc} for further details.
+\exitem{xdy3} This document is like \samplefile{xdy} but uses the
+command \cs{Numberstring} from the \sty{fmtcount} package to
+format the page numbers. This requires at least version 3.03 of
+\sty{fmtcount} to work correctly.
+
\exitem{utf8} This is another example
that uses \gls{xindy}. Unlike \gls{makeindex},
\gls{xindy} can cope with \glspl{nonlatinchar}. This
@@ -1287,10 +1705,9 @@ latex sampleutf8
makeglossaries sampleutf8
latex sampleutf8
\end{prompt}
-If you don't have Perl installed, you will have to call
-\gls{xindy} explicitly instead of using \gls{makeglossaries}
+The explicit \gls{xindy} call is
(no line breaks):
-\begin{prompt}
+\begin{prompt}\raggedright
xindy -L english -C utf8 -I xindy -M sampleutf8 -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo
\end{prompt}
@@ -1301,18 +1718,24 @@ latex sampleutf8
makeglossaries sampleutf8
latex sampleutf8
\end{prompt}
+or
+\begin{prompt}
+latex sampleutf8
+makeglossaries-lite sampleutf8
+latex sampleutf8
+\end{prompt}
you will see that the entries that start with an \gls{exlatinchar}
now appear in the symbols group, and the word \qt{man\oe uvre} is now
-after \qt{manor} instead of before it. If you are unable to use
-\gls{makeglossaries}, the call to \gls{makeindex} is as
-follows (no line breaks):
-\begin{prompt}
+after \qt{manor} instead of before it. If you want to explicitly
+call \gls{makeindex} (no line breaks):
+\begin{prompt}\raggedright
makeindex -s sampleutf8.ist -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo
\end{prompt}
\exitem{-index} This document uses
the \styfmt{glossaries} package to create both a glossary and an
-index. This requires two \gls{makeglossaries} calls to ensure the
+index. This requires two \gls{makeglossaries} (or
+\gls{makeglossaries-lite.lua}) calls to ensure the
document is up to date:
\begin{prompt}
latex sample-index
@@ -1412,65 +1835,132 @@ for testing purposes and are on \TeX's path (in
via \ics{input} or \ics{loadglsentries}. The files are as follows:
\begin{description}
\item[example-glossaries-brief.tex] These entries all have brief
-descriptions.
+descriptions. For example:
+\begin{verbatim}
+\newglossaryentry{lorem}{name={lorem},description={ipsum}}
+\end{verbatim}
\item[example-glossaries-long.tex] These entries all have long
-descriptions.
+descriptions. For example:
+\begin{verbatim}
+\newglossaryentry{loremipsum}{name={lorem ipsum},
+description={dolor sit amet, consectetuer adipiscing
+elit. Ut purus elit, vestibulum ut, placerat ac,
+adipiscing vitae, felis. Curabitur dictum gravida
+mauris.}}
+\end{verbatim}
\item[example-glossaries-multipar.tex] These entries all have
multi-paragraph descriptions.
\item[example-glossaries-symbols.tex] These entries all use the
-\gloskey{symbol} key.
+\gloskey{symbol} key. For example:
+\begin{verbatim}
+\newglossaryentry{alpha}{name={alpha},
+symbol={\ensuremath{\alpha}},
+description={Quisque ullamcorper placerat ipsum.}}
+\end{verbatim}
+
+\item[example-glossaries-symbolnames.tex] Similar to the previous
+file but the \gloskey{symbol} key isn't used. Instead the symbol
+is stored in the \gloskey{name} key. For example:
+\begin{verbatim}
+\newglossaryentry{sym.alpha}{sort={alpha},
+name={\ensuremath{\alpha}},
+description={Quisque ullamcorper placerat ipsum.}}
+\end{verbatim}
\item[example-glossaries-images.tex] These entries use the
\gloskey{user1} key to store the name of an image file. (The images
are provided by the \sty{mwe} package and should be on \TeX's path.)
One entry doesn't have an associated image to help test for a~missing key.
-\item[example-glossaries-acronym.tex] These entries are all acronyms.
+\item[example-glossaries-acronym.tex] These entries are all
+abbreviations. For example:
+\begin{verbatim}
+\newacronym[type=\glsdefaulttype]{lid}{LID}{lorem ipsum
+dolor}
+\end{verbatim}
\item[example-glossaries-acronym-desc.tex] These entries are all
-acronyms that use the \gloskey{description} key.
+abbreviations that use the \gloskey{description} key.
+For example:
+\begin{verbatim}
+\newacronym[type=\glsdefaulttype,
+ description={fringilla a, euismod sodales,
+ sollicitudin vel, wisi}]{ndl}{NDL}{nam dui ligula}
+\end{verbatim}
\item[example-glossaries-acronyms-lang.tex] These entries are all
-acronyms, where some of them have a~translation supplied in the
+abbreviations, where some of them have a~translation supplied in the
\gloskey{user1} key.
+For example:
+\begin{verbatim}
+\newacronym[type=\glsdefaulttype,user1={love itself}]
+ {li}{LI}{lorem ipsum}
+\end{verbatim}
\item[example-glossaries-parent.tex] These are hierarchical entries
where the child entries use the \gloskey{name} key.
+For example:
+\begin{verbatim}
+\newglossaryentry{sedmattis}{name={sed mattis},
+description={erat sit amet}
+
+\newglossaryentry{gravida}{parent={sedmattis},
+ name={gravida},description={malesuada}}
+\end{verbatim}
\item[example-glossaries-childnoname.tex] These are hierarchical entries
where the child entries don't use the \gloskey{name} key.
+For example:
+\begin{verbatim}
+\newglossaryentry{scelerisque}{name={scelerisque},
+ description={at}}
+\end{verbatim}
\item[example-glossaries-cite.tex] These entries use the
\gloskey{user1} key to store a citation key (or comma-separated list
of citation keys). The citations are defined in \texttt{xampl.bib},
which should be available on all modern \TeX\ distributions.
One entry doesn't have an associated citation to help test for a~missing
-key.
+key.
+For example:
+\begin{verbatim}
+\newglossaryentry{fusce}{name={fusce},
+description={suscipit cursus sem},user1={article-minimal}}
+\end{verbatim}
\item[example-glossaries-url.tex] These entries use the
\gloskey{user1} key to store an URL associated with the entry.
+For example:
+\begin{verbatim}
+\newglossaryentry{aenean-url}{name={aenean},
+ description={adipiscing auctor est},
+ user1={http://uk.tug.org/}}
+\end{verbatim}
\end{description}
The sample file \texttt{glossary-lipsum-examples.tex} in the
\texttt{doc\slash latex\slash glossaries\slash samples} directory
uses all these files. See also
\url{http://www.dickimaw-books.com/gallery/#glossaries}.
+The \sty{glossaries-extra} package provides additional test files.
\section{Multi-Lingual Support}
\label{sec:languages}
-As from version 1.17, the \styfmt{glossaries} package can now be
+As from version 1.17, the \styfmt{glossaries} package can be
used with \gls{xindy} as well as \gls{makeindex}. If you
are writing in a language that uses an \gls{exlatinalph} or
-\gls{nonlatinalph} it is recommended that you use \gls*{xindy}
-as \gls*{makeindex} is hard-coded for the non-extended
-\gls{latinalph}. This
-means that 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:
+\gls{nonlatinalph} it's best to use \opt3 (\gls*{xindy})
+or \opt4 (\gls{bib2gls})
+as \gls*{makeindex} (\opt2) is hard-coded for the non-extended
+\gls{latinalph} and \opt1 can performed limited ASCII comparisons.
+
+This means that with \optsor34 you are not restricted to the A,
+\ldots, Z letter groups. If you want to use \gls*{xindy}, remember
+to use the \pkgopt{xindy} package option. For example:
\begin{verbatim}
\documentclass[frenchb]{article}
\usepackage[utf8]{inputenc}
@@ -1478,34 +1968,43 @@ If you want to use \gls*{xindy}, remember to use the
\usepackage{babel}
\usepackage[xindy]{glossaries}
\end{verbatim}
+If you want to use \gls*{bib2gls}, you need to use the
+\pkgopt{record} option with \sty{glossaries-extra} and supply the
+definitions in \texttt{.bib} files. (See the \gls{bib2gls} user
+manual for further details.)
\begin{important}
Note that although a~\gls{nonlatinchar}, such as \'e, looks like a plain
-character in your tex file, with standard \LaTeX\ it's actually a~macro and can therefore
+character in your \filetype{.tex} file, with standard \LaTeX\ it's actually a~macro and can therefore
cause expansion problems. You may need to switch off the field
expansions with \cs{glsnoexpandfields}. This issue doesn't occur
-with \XeLaTeX.
+with \XeLaTeX\ or Lua\LaTeX.
+\end{important}
-If you use a~\gls{nonlatinchar} (or other expandable) character at the start of
-an entry name, you must place it in a group, or it will cause
-a problem for commands that convert the first letter to upper case
-(e.g.\ \ics{Gls}). For example:
+With \sty{inputenc}, if you use a~\gls{nonlatinchar} (or other expandable)
+character at the start of an entry name, you must place it in a group,
+or it will cause a problem for commands that convert the first letter
+to upper case (e.g.\ \ics{Gls}). For example:
\begin{alltt}
\verb|\newglossaryentry}{elite}{name={{|\'e\verb|}lite},|
description=\verb|{select group or class}}|
\end{alltt}
-\end{important}
-(For further details, see the section
-\qt{UTF-8} section in the \sty{mfirstuc} user manual.)
-
-If you use the \sty{inputenc} package, \gls{makeglossaries}
-will pick up the encoding from the auxiliary file. If you use
+(With newer versions of \sty{mfirstuc} and \sty{datatool-base} you
+may be able to omit this grouping.)
+For further details, see the \qt{UTF-8} section in the
+\sty{mfirstuc} user manual.
+
+If you are using \gls{xindy} or \gls{bib2gls}, the application needs
+to know the encoding of the \filetype{.tex} file. This information
+is added to the \filetype{.aux} file and can be picked up by
+\gls{makeglossaries} and \gls{bib2gls}. If you use
\gls{xindy} explicitly instead of via \gls*{makeglossaries},
you may need to specify the encoding using the \xdyopt{C}
-option. Read the \gls*{xindy} manual for further details.
+option. Read the \gls*{xindy} manual for further details of this
+option.
As from v4.24, if you are writing in German (for example, using the \sty{ngerman}
-package or \sty{babel} with the \pkgopt{ngerman} package option),
+package\footnote{deprecated, use \styfmt{babel} instead} or \sty{babel} with the \pkgopt{ngerman} package option),
and you want to use \gls{makeindex}['s] \mkidxopt{g} option, you'll
need to change \gls{makeindex}['s] quote character using:
\begin{definition}[\DescribeMacro\GlsSetQuote]
@@ -1681,13 +2180,6 @@ Examples of use:
\usepackage{glossaries}
\end{verbatim}
-\item Using \sty{ngerman}:
-\begin{verbatim}
-\documentclass{article}
-\usepackage{ngerman}
-\usepackage{glossaries}
-\end{verbatim}
-
\end{itemize}
Due to the varied nature of glossaries, it's likely that the
@@ -1697,7 +2189,10 @@ predefined translations may not be appropriate. If you are using the
the words babel uses}. If you are using the \sty{translator}
package, then you can provide your own dictionary with the necessary
modifications (using \cs{deftranslation}) and load it using
-\cs{usedictionary}.
+\cs{usedictionary}. If you simply want to change the title of a
+glossary, you can use the \gloskey[printglossary]{title} key in
+commands like \cs{printglossary} (but not the iterative commands
+like \cs{printglossaries}).
\begin{important}
Note that the \sty{translator} dictionaries are loaded at the beginning of the
@@ -1746,11 +2241,12 @@ option \pkgopt[babel]{translate}. For example:
}
\end{verbatim}
-Note that \gls{xindy} provides much better multi-lingual support
-than \gls{makeindex}, so I~recommend that you use \gls*{xindy}
+Note that \gls{xindy} and \gls{bib2gls} provide much better multi-lingual support
+than \gls{makeindex}, so I~recommend that you use \optsor34
if you have glossary entries that contain
\glspl{nonlatinchar}. See \sectionref{sec:xindy} for further
-details.
+details on \gls{xindy}, and see the \gls{bib2gls} user manual for
+further details of that application.
\subsubsection{Creating a New Language Module}
\label{sec:newlang}
@@ -1982,13 +2478,13 @@ the appropriate UTF-8 characters.
\begin{important}
This section is only applicable if you have chosen \optsor23. You can
-ignore this section if you have chosen \opt1. If you want to
+ignore this section if you have chosen any of the other options. If you want to
alphabetically sort your entries always remember to use the
\gloskey{sort} key if the \gloskey{name} contains any \LaTeX\ commands.
\end{important}
If this section seriously confuses you, and you can't work out how
-to run \gls{makeglossaries} or \gls{makeindex}, you can try using
+to run external tools like \gls{makeglossaries} or \gls{makeindex}, you can try using
the \pkgopt{automake} package option, described in
\sectionref{sec:pkgopts-sort}, but you will need \TeX's shell escape
enabled.
@@ -1996,25 +2492,34 @@ enabled.
In order to generate a sorted glossary with compact
\glspl{numberlist}, it is necessary to use an external
\gls{indexingapp} as an intermediate step (unless you have chosen
-\opt1, which uses \TeX\ to do the sorting). It is this application
-that creates the file containing the code that typesets the
+\opt1, which uses \TeX\ to do the sorting or \opt5, which doesn't
+perform any sorting). It is this application
+that creates the file containing the code required to typeset the
glossary. \textbf{If this step is omitted, the glossaries will not
appear in your document.} The two \glspl*{indexingapp} that are most
commonly used with \LaTeX\ are \gls{makeindex} and \gls{xindy}. As
from version 1.17, the \styfmt{glossaries} package can be used with
either of these applications. Previous versions were designed to be
-used with \gls*{makeindex} only. Note that \gls*{xindy} has much
+used with \gls*{makeindex} only. With the \sty{glossaries-extra} package, you
+can also use \gls{bib2gls} as the indexing application. (See
+the \sty{glossaries-extra} and \gls{bib2gls} user manuals for
+further details.) Note that \gls*{xindy} and \gls*{bib2gls} have much
better multi-lingual support than \gls*{makeindex}, so \gls*{xindy}
-is recommended if you're not writing in English. Commands that only
-have an effect when \gls*{xindy} is used are described in
-\sectionref{sec:xindy}.
+or \gls*{bib2gls} are recommended if you're not writing in English.
+Commands that only have an effect when \gls*{xindy} is used are
+described in \sectionref{sec:xindy}.
\begin{important}
This is a multi-stage process, but there are methods of automating
document compilation using applications such as \app{latexmk} and
-\app{arara}. See
-\url{http://www.dickimaw-books.com/latex/thesis/html/build.html} for
-more information.
+\app{arara}. With \app{arara} you can just add special comments to
+your document source:
+\begin{alltt}
+\% arara: pdflatex
+\% arara: makeglossaries
+\% arara: pdflatex
+\end{alltt}
+With \app{latexmk} you need to set up the required dependencies.
\end{important}
The \styfmt{glossaries} package comes with the Perl script
@@ -2023,11 +2528,12 @@ on all the glossary files using a customized style file (which is
created by \ics{makeglossaries}). See
\sectionref{sec:makeglossariesapp} for further
details. Perl is stable, cross-platform, open source software that
-is used by a number of \TeX-related applications. Most Unix-like
+is used by a number of \TeX-related applications (including
+\gls*{xindy} and \app{latexmk}). Most Unix-like
operating systems come with a~Perl interpreter. \TeX~Live also comes
with a~Perl interpreter. MiK\TeX\ doesn't come with a~Perl
interpreter so if you are a~Windows MiK\TeX\ user you will need to
-install Perl if you want to use \gls{makeglossaries}.
+install Perl if you want to use \gls{makeglossaries} or \gls{xindy}.
Further information is available at \url{http://www.perl.org/about.html}
and
\href{http://tex.stackexchange.com/questions/158796/miktex-and-perl-scripts-and-one-python-script}{MiKTeX and Perl scripts (and one Python script)}.
@@ -2050,12 +2556,11 @@ file and see if you can work it out from the \gls*{makeindex} or
\item If \gls{makeindex} warns about multiple encap values,
\gls{makeglossaries} will detect this and attempt to correct the
-problem.\footnote{Added to version \gls{makeglossaries} 2.18.} Since
-\gls{xindy} doesn't warn about this, this correction is only
-provided by \gls{makeglossaries} when \gls{makeindex} is used.
-(\gls{xindy} uses the order of the attributes list to determine
-which format should take precedence. See \cs{GlsAddXdyAttribute} in
-\sectionref{sec:xindyloc}.)
+problem.\footnote{Added to version \gls{makeglossaries} 2.18.} This
+correction is only provided by \gls{makeglossaries} when
+\gls{makeindex} is used since \gls{xindy} uses the order of the
+attributes list to determine which format should take precedence.
+(See \cs{GlsAddXdyAttribute} in \sectionref{sec:xindyloc}.)
\end{itemize}
@@ -2205,20 +2710,11 @@ wrapper for the \gls{makeglossaries} Perl script. MiKTeX also
provides a~wrapper \texttt{makeglossaries.exe} but doesn't provide
a~Perl interpreter, which is still required even if you run MiKTeX's
\texttt{makeglossaries.exe}, so with MiKTeX you'll need to install
-Perl. There's more information about this at
+Perl.\footnote{The batch file \texttt{makeglossaries.bat} has been
+removed since the \TeX\ distributions for Windows provide
+\texttt{makeglossaries.exe}.} There's more information about this at
\url{http://tex.stackexchange.com/q/158796/19862} on the TeX.SX
-site. Alternatively, there is a batch file called
-\texttt{makeglossaries.bat} that should be located in the same
-folder as the \gls{makeglossaries} Perl script. This just explicitly
-loads the script into Perl. If you've installed Perl but for some
-reason your operating system can't find \texttt{perl.exe}, you can
-edit the \texttt{makeglossaries.bat} file to include the full path
-to \texttt{perl.exe} (but take care as this file will be overwritten
-next time you update the \styfmt{glossaries} package). If you move
-the \texttt{.bat} file to a new location, you will also need to
-supply the full path to the \gls{makeglossaries} Perl script. (Don't
-also move the Perl script as well or you may miss out on updates to
-\gls{makeglossaries}.)
+site.
The \gls{makeglossaries} script attempts to fork the
\gls{makeindex}\slash\gls{xindy} process using \texttt{open()} on the
@@ -2280,10 +2776,10 @@ resulting file onto the man path. Alternatively do
\begin{important}
When upgrading the \styfmt{glossaries} package, make sure you also
upgrade your version of \gls{makeglossaries}. The current version is
-2.21.
+4.33.
\end{important}
-\subsection{Using the makeglossaries-lite.lua Lua Script}
+\subsection{Using the makeglossaries-lite Lua Script}
\label{sec:makeglossarieslua}
The Lua alternative to the \gls{makeglossaries} Perl script requires
@@ -2341,7 +2837,7 @@ files, you must make sure you have used the
\end{verbatim}
This is required regardless of whether you use \gls{xindy}
explicitly or whether it's called implicitly via applications such
-as \gls{makeglossaries} or \gls{makeglossariesgui}. This causes the glossary
+as \gls{makeglossaries}. This causes the glossary
entries to be written in raw \gls*{xindy} format, so you need to
use \xdyopt{I}\texttt{ xindy} \emph{not} \xdyopt{I}\texttt{ tex}.
@@ -2502,7 +2998,11 @@ If \opt1 has been used, the \texttt{.aux} file will contain
\begin{definition}
\cs{@gls@reference}\marg{type}\marg{label}\marg{location}
\end{definition}
-for every time an entry has been referenced.
+for every time an entry has been referenced. If \opt4 has been
+used, the \texttt{.aux} file will contain one or more instances of
+\begin{definition}
+\cs{glsxtr@resource}\marg{options}\marg{basename}
+\end{definition}
\chapter{Package Options}
\label{sec:pkgopts}
@@ -2510,6 +3010,8 @@ for every time an entry has been referenced.
This section describes the available \styfmt{glossaries} package
options. You may omit the \texttt{=true} for boolean options. (For
example, \pkgopt{acronym} is equivalent to \pkgopt[true]{acronym}).
+The \gls{glossaries-extra} package has additional options described
+in the \gls*{glossaries-extra} manual.
\begin{important}
Note that \meta{key}=\meta{value} package options can't be passed via the
@@ -2530,6 +3032,9 @@ the \styfmt{glossaries} package. Don't use this option if you're new to using
common mistakes (such as forgetting to use \ics{makeglossaries}).
Note that the \pkgopt[true]{debug} and \pkgopt[showtargets]{debug} will override this option.
+\item[\pkgopt{nolangwarn}] This suppresses the warning generated by
+a missing language module.
+
\item[\pkgopt{noredefwarn}] If you load \styfmt{glossaries} with
a~class or another package that already defines glossary related
commands, by default \styfmt{glossaries} will warn you that it's
@@ -2540,8 +3045,10 @@ warnings. Other warnings will still be issued unless you use the
\pkgopt{nowarn} option described above.
\item[\pkgopt{debug}] Introduced in version 4.24.
-This was a boolean option but as from v4.32 it's now a choice
-option. If no value is given, \pkgopt[true]{debug} is assumed.
+The default setting is \pkgopt[false]{debug}.
+This was a boolean option but as from v4.32 it now accepts the
+values: \pkgoptfmt{false}, \pkgoptfmt{true} and
+\pkgoptfmt{showtargets}. If no value is given, \pkgopt[true]{debug} is assumed.
Both \pkgopt[true]{debug} and \pkgopt[showtargets]{debug}
switch on the debug mode (and will automatically
cancel the \pkgopt{nowarn} option). The \pkgopt[showtargets]{debug}
@@ -2549,16 +3056,25 @@ option will additionally use
\begin{definition}[\DescribeMacro\glsshowtarget]
\cs{glsshowtarget}\marg{target name}
\end{definition}
-to show the hypertarget\slash hyperlink name in the margin when
+to show the hypertarget or hyperlink name in the margin when
\cs{glsdohypertarget} is used by commands like \cs{glstarget}
and when \cs{glsdohyperlink} is used by commands like \cs{gls}.
+This puts the information in the margin using \ics{marginpar}.
+If this causes a problem, you'll need to redefine
+\cs{glsshowtarget}. For example:
+\begin{verbatim}
+\renewcommand*{\glsshowtarget}[1]{\texttt{\small [#1]}}
+\end{verbatim}
-Consider the following example document:
+The purpose of the debug mode can be demonstrated with
+the following example document:
\begin{verbatim}
\documentclass{article}
\usepackage{glossaries}
-\newglossaryentry{sample1}{name={sample1},description={example}}
-\newglossaryentry{sample2}{name={sample2},description={example}}
+\newglossaryentry{sample1}{name={sample1},
+ description={example}}
+\newglossaryentry{sample2}{name={sample2},
+ description={example}}
\glsadd{sample2}
\makeglossaries
\begin{document}
@@ -2566,31 +3082,39 @@ Consider the following example document:
\printglossaries
\end{document}
\end{verbatim}
-Here, only the \texttt{sample1} entry has been indexed, even
+In this case, only the \texttt{sample1} entry has been indexed, even
though \verb|\glsadd{sample2}| appears in the source code.
-This is because the associated file is opened by
-\ics{makeglossaries}, but \verb|\glsadd{sample2}| has been used
-before this command. Since the file isn't open yet, the
-information can't be written to it, which is why the
-\texttt{sample2} entry doesn't appear in the glossary.
+This is because \verb|\glsadd{sample2}| has been used before the
+associated file is opened by \ics{makeglossaries}. Since the file
+isn't open yet, the information can't be written to it, which is why
+the \texttt{sample2} entry doesn't appear in the glossary.
This situation doesn't cause any errors or warnings as it's
perfectly legitimate for a user to want to use \styfmt{glossaries}
to format the entries (e.g.\ abbreviation expansion) but not display
any lists of terms, abbreviations, symbols etc.
-Without \cs{makeglossaries} (or \cs{makenoidxglossaries})
-the indexing is suppressed but, other than that, commands
-like \cs{gls} behave as usual.
+Without \cs{makeglossaries} the indexing is suppressed but, other
+than that, commands like \cs{gls} behave as usual. It's also
+possible that the user may want to temporarily comment out
+\cs{makeglossaries} in order to suppress the indexing while working
+on a draft version to speed compilation. Therefore
+\cs{makeglossaries} can't be used to enable \cs{newglossaryentry}
+and \cs{glsadd}. They must be enabled by default. (It does, however,
+enable the \gloskey{see} key as that's a more common problem. See
+below.)
The debug mode, enabled with the \pkgopt{debug} option,
+\begin{verbatim}
+\usepackage[debug]{glossaries}
+\end{verbatim}
will write information to the log file when the indexing
can't occur because the associated file isn't open.
The message is written in the form
\begin{quote}
-Package glossaries Info: wrglossary(\meta{type})(\meta{line}) on
+Package glossaries Info: wrglossary(\meta{type})(\meta{text}) on
input line \meta{line number}.
\end{quote}
-where \meta{type} is the glossary label and \meta{line} is the line
+where \meta{type} is the glossary label and \meta{text} is the line
of text that would've been written to the associated file if
it had been open. So if any entries haven't appeared in the
glossary but you're sure you used commands like \cs{glsadd}
@@ -2607,7 +3131,9 @@ Since this is easy to miss, the \styfmt{glossaries} package by
default issues an error message if the \gloskey{see} key is used
before \cs{makeglossaries}. This option allows you to change the
error into just a warning (\pkgopt[warn]{seenoindex}) or
-ignore it (\pkgopt[ignore]{seenoindex}).
+ignore it (\pkgopt[ignore]{seenoindex}) if, for example, you want
+to temporarily comment out \cs{makeglossaries} to speed up the
+compilation of a draft document by omitting the indexing.
\item[\pkgopt{nomain}] This suppresses the creation of the main
glossary and associated \texttt{.glo} file, if unrequired. Note that
@@ -2621,7 +3147,8 @@ put all your entries (either via the \pkgopt{acronym} (or
\begin{important}
If you don't use the main glossary and you don't use this option,
-\gls{makeglossaries} will produce the following warning:
+\gls{makeglossaries} will produce a warning.
+\end{important}
\begin{alltt}
Warning: File '\emph{filename}.glo' is empty.
Have you used any entries defined in glossary
@@ -2632,7 +3159,6 @@ you don't want to use the main glossary.
If you did actually want to use the main glossary and you see this
warning, check that you have referenced the entries in that glossary
via commands such as \ics{gls}.
-\end{important}
\item[\pkgopt{sanitizesort}] This is a boolean option that
determines whether or not to \gls{sanitize} the sort value when
@@ -2669,17 +3195,18 @@ glossaries or if you are using a class or other packages that
create a lot of external files, you may exceed the maximum number
of available registers. If \pkgopt{savewrites} is set, the glossary
information will be stored in token registers until the end of the
-document when they will be written to the external files. If you run
-out of token registers, you can use \sty{etex}.
+document when they will be written to the external files.
\begin{important}
-This option can significantly slow document compilation. As an
-alternative, you can use the \sty{scrwfile} package (part of the
-KOMA-Script bundle) and not use this option.
+This option can significantly slow document compilation and may
+cause the indexing to fail. Page numbers in the \gls{numberlist}
+will be incorrect on page boundaries due to \TeX's asynchronous
+output routine. As an alternative, you can use the \sty{scrwfile}
+package (part of the KOMA-Script bundle) and not use this option.
\end{important}
You can also reduce the number of write registers by using
-\opt1 or by ensuring you define all your glossary entries in the
+\optsor14 or by ensuring you define all your glossary entries in the
preamble.
\begin{important}
@@ -2696,6 +3223,7 @@ document to avoid rewriting the files. For example:
\let\glswritefiles\relax
\end{verbatim}
\end{important}
+In general, this package option is best avoided.
\item[\pkgopt{translate}] This can take the following values:
@@ -3178,9 +3706,32 @@ Instead you must either use \ics{setglossarystyle}\marg{style} or the
\setglossarystyle{mcoltree}
\end{verbatim}
+\item[\pkgopt{esclocations}] This is a boolean option. (The default
+is \pkgopt[true]{esclocations}.) Both \gls{makeindex} and \gls{xindy}
+are fussy about the location formats (\gls{makeindex} more so than
+\gls{xindy}) so the \styfmt{glossaries} package tries to ensure that
+special characters are escaped and allows for the location to be
+substituted for a format that's more acceptable to the indexing
+application. This requires a bit of trickery to circumvent the
+problem posed by \TeX's asynchronous output routine, which can go
+wrong and also adds to the complexity of the document build.
+
+If you're sure that your locations will always expand to an
+acceptable format (or you're prepared to post-process the glossary
+file before passing it to the relevant indexing application) then
+use \pkgopt[false]{esclocations} to avoid the complex escaping
+of location values.
+
\item[\pkgopt{nonumberlist}] This option will suppress the
associated \glspl{numberlist} in the glossaries (see also
-\sectionref{sec:numberlists}).
+\sectionref{sec:numberlists}). Note that if you use \optsor23
+(\gls{makeindex} or \gls{xindy}) then the locations must still be
+valid. This package option merely prevents the \gls{numberlist}
+from being displayed, but both \gls{makeindex} and \gls{xindy}
+still require a location or cross-reference for each term that's
+indexed. Remember that \gls{numberlist} includes any
+cross-references, so suppressing the \gls{numberlist} will also hide
+the cross-references (see below).
\item[\pkgopt{seeautonumberlist}] If you suppress the
\glspl{numberlist} with \pkgopt{nonumberlist}, described above, this
@@ -3250,14 +3801,16 @@ redefined, if required, before the entries are defined (in the
case of \pkgopt[def]{sort}) or before the entries are used
(in the case of \pkgopt[use]{sort}).
-\item \pkgoptval{none}{sort} : this option is new to version 4.30
-and is only for documents that don't use \cs{makeglossaries}
-or \cs{makenoidxglossaries}. It omits the code used to sanitize
-or escape the sort value, since it's not required. This option
+\item \pkgoptval{none}{sort} : this setting is new to version 4.30
+and is only for documents that don't use \cs{makeglossaries} (\optsor23)
+or \cs{makenoidxglossaries} (\opt1). It omits the code used to sanitize
+or escape the sort value, since it's not required. This can help to
+improve the document build speed, especially if there are a large
+number of entries. This option
can't be used with \cs{printglossary} or \cs{printnoidxglossary}
(or the iterative versions \cs{printglossaries} or
\cs{printnoidxglossaries}). It may be used with
-\sty{glossaries-extra}'s \cs{printunsrtglossary}.
+\sty{glossaries-extra}'s \cs{printunsrtglossary} (\opt5).
\end{itemize}
Note that the group styles (such as \glostyle{listgroup}) are
incompatible with the \pkgopt[use]{sort} and \pkgopt[def]{sort}
@@ -3842,7 +4395,9 @@ started to define entries, you may get unexpected results.
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.
+a~document, although some combinations are possible with
+\gls*{glossaries-extra}. (For \optsand45 see the \gls{bib2gls} and
+\gls{glossaries-extra} manuals.)
\section[Option 1]{\ifpdf\opt1\else Option 1\fi}
\label{sec:setupopt1}
@@ -3942,13 +4497,19 @@ better to define them in the preamble to ensure this. In fact, some
commands such as \cs{longnewglossaryentry}
may only be used in the preamble. See \sectionref{sec:docdefs} for
a discussion of the problems with defining entries within the
-document instead of in the preamble.
+document instead of in the preamble. (The \gls{glossaries-extra}
+package has an option that provides a restricted form of document
+definitions that avoids some of the issues discussed in
+\sectionref{sec:docdefs}.)
\begin{important}
\opt1 enforces the preamble-only restriction on
-\ics{newglossaryentry}.
+\ics{newglossaryentry}. \opt4 requires that definitions are provided
+in \texttt{.bib} format. \opt5 requires either preamble-only
+definitions or the use of the \sty{glossaries-extra} package option
+\optfmt{docdef=restricted}.
\end{important}
-Only those entries that are referenced in the document
+Only those entries that are indexed in the document
(using any of the commands described in
\sectionref{sec:glslink}, \sectionref{sec:glsadd} or
\sectionref{sec:crossref}) will appear in the glossary. See
@@ -3978,9 +4539,8 @@ hasn't already been defined:
\begin{definition}[\DescribeMacro\provideglossaryentry]
\cs{provideglossaryentry}\marg{label}\marg{key=value list}
\end{definition}
-and\par
-\DescribeMacro\longprovideglossaryentry
-\begin{definition}
+and
+\begin{definition}[\DescribeMacro\longprovideglossaryentry]
\cs{longprovideglossaryentry}\marg{label}\marg{key=value
list}\marg{long description}
\end{definition}
@@ -4012,8 +4572,13 @@ The description is set in the third argument of
\cs{longnewglossaryentry} and \cs{longprovideglossaryentry}. With
the other commands it's set via the \gloskey{description} key.
As is typical with \meta{key}=\meta{value} lists, values that contain
-a comma or equal sign must be enclosed in
-braces. Available fields are listed below:
+a comma or equal sign must be enclosed in braces. Available fields
+are listed below. Additional fields are provided by the
+supplementary packages \sty{glossaries-prefix}
+(\sectionref{sec:prefix}) and \sty{glossaries-accsupp}
+(\sectionref{sec:accsupp}) and also by \gls{glossaries-extra}.
+You can also define your own custom keys (see
+\sectionref{sec:addkey}).
\begin{description}
\item[{\gloskey{name}}] The name of the entry (as it will appear in
@@ -4190,9 +4755,6 @@ Six keys provided for any additional information the user may want
to specify. (For example, an associated dimension or an alternative
plural or some other grammatical construct.) Alternatively, you can
add new keys using \ics{glsaddkey} or \ics{glsaddstoragekey} (see \sectionref{sec:addkey}).
-Other keys are also provided by the \sty{glossaries-prefix}
-(\sectionref{sec:prefix}) and \sty{glossaries-accsupp}
-(\sectionref{sec:accsupp}) packages.
\item[{\gloskey{nonumberlist}}] A boolean key. If the value is
missing or is \texttt{true}, this will suppress the \gls{numberlist} just for
@@ -4202,8 +4764,8 @@ for this entry with \gloskey{nonumberlist=false}.
(See \sectionref{sec:numberlists}.)
\item[{\gloskey{see}}] Cross-reference another entry. Using the
-\gloskey{see} key will automatically add this entry to the
-glossary, but will not automatically add the cross-referenced entry.
+\gloskey{see} key will \emph{automatically add this entry to the
+glossary}, but will not automatically add the cross-referenced entry.
The referenced entry should be supplied as the value to this key.
If you want to override the \qt{see} tag, you can supply the new
tag in square brackets before the label. For example
@@ -4224,21 +4786,24 @@ 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
-has no effect for entries defined in the \env{document} environment.
+should not be used with entries defined in the \env{document} environment.
\end{important}
+Since it's useful to suppress the indexing while working on a draft
+document, consider using the \pkgopt{seenoindex} package option to
+warn or ignore the \gloskey{see} key while \cs{makeglossaries} is
+commented out.
If you use the \gloskey{see} key, you may want to consider using the
-supplementary \gls{glossaries-extra} package.
+\gls{glossaries-extra} package which additionally
+provides a \texttt{seealso} and \texttt{alias} key. If you want to
+avoid the automatic indexing triggered by the \gloskey{see} key,
+consider using \opt4.
\end{description}
The following keys are reserved for \ics{newacronym} (see
\sectionref{sec:acronyms}): \gloskey{long}, \gloskey{longplural},
-\gloskey{short} and \gloskey{shortplural}. Additional keys are
-provided by the \sty{glossaries-prefix} (\sectionref{sec:prefix})
-and the \sty{glossaries-accsupp} (\sectionref{sec:accsupp}) packages.
-You can also define your own custom keys (see
-\sectionref{sec:addkey}).
+\gloskey{short} and \gloskey{shortplural}.
\begin{important}
Avoid using any of the \glslike\ or \glstextlike\ commands within
@@ -4510,8 +5075,8 @@ Suppose I want to define acronyms and other forms of abbreviations,
such as initialisms, but I want them all in the same glossary and I
want the acronyms on first use to be displayed with the short form followed by
the long form in parentheses, but the opposite way round for other
-forms of abbreviations.\footnote{The \gls{glossaries-extra} package
-provides a simpler way of achieving this.}
+forms of abbreviations. (The \gls{glossaries-extra} package
+provides a simpler way of achieving this.)
Here I can define a new key that determines whether the term is
actually an acronym rather than some other form of abbreviation. I'm
@@ -4533,7 +5098,8 @@ determine how to display the full form:
\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
}
{% Put the long form in the description
- \renewcommand*{\GenericAcronymFields}{description={\the\glslongtok}}%
+ \renewcommand*{\GenericAcronymFields}{%
+ description={\the\glslongtok}}%
% For the full format, test the value of the "abbrtype" key.
% If it's set to "word" put the short form first with
% the long form in brackets.
@@ -4585,7 +5151,8 @@ determine how to display the full form:
}%
}%
% Just use the short form as the name part in the glossary:
- \renewcommand*{\acronymentry}[1]{\acronymfont{\glsentryshort{##1}}}%
+ \renewcommand*{\acronymentry}[1]{%
+ \acronymfont{\glsentryshort{##1}}}%
% Sort by the short form:
\renewcommand*{\acronymsort}[2]{##1}%
% Just use the surrounding font for the short form:
@@ -4655,7 +5222,8 @@ to determine whether or not to reference the value of this new
The new acronym style has a~minor modification that forces the user
to specify a description. In the previous example, the line:
\begin{verbatim}
- \renewcommand*{\GenericAcronymFields}{description={\the\glslongtok}}%
+ \renewcommand*{\GenericAcronymFields}{%
+ description={\the\glslongtok}}%
\end{verbatim}
needs to be changed to:
\begin{verbatim}
@@ -4754,8 +5322,7 @@ below the deck.
\end{description}
(for contractions).
-For a complete document, see the sample file
-\samplefile{-storage-abbr-desc}.
+For a complete document, see \samplefile{-storage-abbr-desc}.
\end{example}
\section{Expansion}
@@ -4957,7 +5524,10 @@ type has been specified by \ics{glsdefaulttype}, which is what
\ics{newglossaryentry} uses by default).
This is a~preamble-only command. You may also use \ics{input} to load
-the file but don't use \ics{include}.
+the file but don't use \ics{include}. If you find that your file is
+becoming unmanageably large, you may want to consider switching to
+\gls{bib2gls} and use an application such as JabRef to manage the
+entry definitions.
\begin{important}
If you want to use \ics{AtBeginDocument} to \cs{input} all your entries
@@ -5152,6 +5722,14 @@ occur; the \gloskey{see} key isn't stored, which means it can't be
added to the \filetype{.glsdefs} file when it's created at the end of the
document (and therefore won't be present on subsequent runs).
+The \gls{glossaries-extra} package provides a setting (but only for
+\optsand23) that allows \cs{newglossaryentry} to occur in the
+document environment but doesn't create the \filetype{.glsdefs}
+file. This circumvents some problems but it means that you can't
+display any of the glossaries before all the entries have been
+defined (so it's all right if all the glossaries are at the end of
+the document but not if any occur in the front matter).
+
\subsection{Good Practice Issues}
\label{sec:goodpractice}
@@ -5182,66 +5760,218 @@ definition.
Each entry in the glossary has an associated \gls{numberlist}.
By default, these numbers refer to the pages on which that entry has
-been used (using any of the commands described in
+been indexed (using any of the commands described in
\sectionref{sec:glslink} and \sectionref{sec:glsadd}). The number
list can be suppressed using the \pkgopt{nonumberlist} package
option, or an alternative counter can be set as the default using
the \pkgopt{counter} package option. The number list is also
referred to as the location list\index{location list|see{number list}}.
+\Glspl{numberlist} are more common with indexes rather than
+glossaries (although you can use the \styfmt{glossaries} package for
+indexes as well). However, the \styfmt{glossaries} package makes use
+of \gls{makeindex} or \gls{xindy} to hierarchically sort and collate the
+entries since they are readily available with most modern \TeX\
+distributions. Since these are both designed as \glspl{indexingapp}
+they both require that terms either have a valid location or a
+cross-reference. Even if you use \pkgopt{nonumberlist}, the
+locations must still be provided and acceptable to the
+\gls{indexingapp} or they will cause an error during the indexing
+stage, which will interrupt the document build. However, if you're
+not interested in the locations, each entry only needs to be indexed
+once, so consider using \pkgopt{indexonlyfirst}, which can improve the
+document build time by only indexing the \gls{firstuse} of each term.
+
+The \ics{glsaddall} command (see \sectionref{sec:glsadd}), which is used to
+automatically index all entries, iterates over all defined entries
+and does \cs{glsadd}\marg{label} for each entry (where \meta{label}
+is that entry's label). This means that \cs{glsaddall} automatically
+adds the same location to every entry's \gls{numberlist}, which
+looks weird if the \gls*{numberlist} hasn't been suppressed.
+
+With \opt4, the indexing is performed by \gls{bib2gls}, which was
+specifically designed for the \gls{glossaries-extra} package. So it
+will allow any location format, and its \texttt{selection=all}
+option will select all entries without adding an unwanted location to the
+\gls{numberlist}. If \gls{bib2gls} can deduce a numerical value for
+a location, it will attempt to form a range over consecutive
+locations, otherwise it won't try to form a range and the
+location will just form an individual item in the list.
+\opt1 also allows any location but it doesn't form ranges.
+
+\section{Encap Values}
+\label{sec:encap}
+
Each location in the \gls{numberlist} is encapsulated with a
-command. (The \termdef{encap} value.) By default this is the
-\ics{glsnumberformat} command, but 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. Complications can arise if you use different encap
-values for the same location. For example, suppose on page~10 you
-have both the default \cs{glsnumberformat} and \cs{textbf} encaps.
-While it may seem apparent that \cs{textbf} should override
-\cs{glsnumberformat} in this situation, neither \gls{makeindex} nor
-\gls{xindy} know this. In the case of \gls{xindy}, it only accepts
-one encap and discards the other for identical locations. The encap
-it chooses to keep may not necessarily be the one you want. 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 fonts.
-
-This is something you need to be careful about, but if you use the
-\gls{makeglossaries} Perl script it will detect \gls{makeindex}'s
-warning and attempt to fix the problem.\footnote{This feature was
-introduced in \gls{makeglossaries} version 2.18.} Since \gls{xindy}
-doesn't generate a warning, \gls{makeglossaries} won't do anything
-about it if you are using \gls{xindy}. With \gls{makeindex},
-\gls{makeglossaries} will let the encaps override each other,
-similar to \gls{xindy}, except that the \cs{glsnumberformat} encap
-will always have the least precedence. Other conflicting encaps will
-have the last one override earlier ones for the same location.
-
-Due to the asynchronous nature of \TeX's output routine (see,
-for example,
+command formed from the \termdef{encap} value. By
+default this is the \ics{glsnumberformat} command, which corresponds
+to the encap \texttt{glsnumberformat}, but this may be
+overridden using the \gloskey[glslink]{format} key in the optional
+argument to commands like \cs{gls}. (See \sectionref{sec:glslink}.)
+For example, you may want the location to appear in bold to indicate
+the principle use of a term or symbol. If the encap starts with an
+open parenthesis~\verb|(| this signifies the start of a range and if
+the encap starts with close parenthesis~\verb|)| this signifies the
+end of a range. These must always occur in matching pairs.
+
+The \styfmt{glossaries} package provides the command \ics{glsignore}
+which ignores its argument. This is the format used by
+\cs{glsaddallunused} to suppress the location, which works fine as
+long as no other locations are added to the \gls{numberlist}. For
+example, if you use \verb|\gls{sample}| on page~2 then reset the
+\gls{firstuseflag} and then use \cs{glsaddallunused} on page~10, the
+\gls{numberlist} for \texttt{sample} will be \verb|2, \glsignore{10}|
+which will result in \qt{2,~} which has a spurious comma.
+
+This isn't a problem with \gls{bib2gls} because you'd use
+\texttt{selection=all} instead of \cs{glsaddallunused}, but even if
+you explicitly had, for example,
+\cs{gls}\texttt{[format=glsignore]}\marg{label}
+for some reason, \gls{bib2gls} will recognise \texttt{glsignore} as
+a special encap indicating an ignored location, so it will select
+the entry but not add that location to the \gls{numberlist}. It's a
+problem for all the other options (except \opt5, which doesn't
+perform any indexing).
+
+Complications can arise if you use different encap values for the
+same location. For example, suppose on page~10 you have both the
+default \texttt{glsnumberformat} and \texttt{textbf} encaps. While it may
+seem apparent that \texttt{textbf} should override \texttt{glsnumberformat}
+in this situation, the \gls{indexingapp} may not know it.
+This is therefore something you need to be careful about if you use the
+\gloskey[glslink]{format} key or if you use a command that
+implicitly sets it.
+
+In the case of \gls{xindy}, it only accepts one encap (according to
+the order of precedence given in the \gls{xindy} module) and discards the
+others for identical locations (for the same entry). This can cause
+a problem if a discarded location forms the start or end of a range.
+
+In the case of \gls{makeindex}, it accepts different encaps for the
+same location, but warns about it. This leads to a \gls{numberlist}
+with the same location repeated in different formats. If you use
+the \gls{makeglossaries} Perl script with \opt2 it will detect
+\gls{makeindex}'s warning and attempt to fix the problem, ensuring
+that the \texttt{glsnumberformat} encap always has the least precedence
+unless it includes a range identifier. Other conflicting encaps will
+have the last one override earlier ones for the same location with
+range identifiers taking priority.
+
+No discard occurs with \opt1 so again you get the same location
+repeated in different formats. With \opt4, \gls{bib2gls} will discard
+according to order of precedence, giving priority to start and end
+range encaps. (See the \gls{bib2gls} manual for further details.)
+
+\section{Locations}
+\label{sec:locationsyntax}
+
+Neither \opt1 nor \opt4 care about the location syntax as long as
+it's valid \LaTeX\ code (and doesn't contain fragile commands). In
+both cases, the indexing is performed by writing a line to the
+\texttt{.aux} file. The write operation is deferred to avoid the
+problems associated with \TeX's asynchronous output routine.
+(See, for example,
\href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}{Finding
-if you're on an odd or an even page}) the \texttt{page} counter
-(represented internally as \cs{c@page}) can be unreliable.
-This can cause problems when glossary entries are referenced in a
-paragraph that spans a page break. The standard \cs{label} mechanism
-deals with this by deferring the write until the end of the
-paragraph, but the \styfmt{glossaries} indexing mechanism
-needs to take into account the possibility that the location might
-contain any of \gls{xindy}['s] special characters which will need to
-be escaped before the write can be performed. (This isn't a problem
-with \gls{makeindex} as that places restrictions on the location
-format which prevent this from happening, but these very
-restrictions can make \gls*{xindy} preferable.)
-
-To compensate, the
-\styfmt{glossaries} package has to make some adjustments to ensure
-the location number is correct for this situation. By default,
-the adjustments only affect the counter styles: \texttt{roman},
-\texttt{Roman}, \texttt{alph}, \texttt{Alph} and \texttt{arabic}.
-If you have a different numbering system where
+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} you need to use:
+\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}
@@ -5265,13 +5995,14 @@ page-spanning paragraphs, you need to do:
\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.)
+this provided the inner command is expandable.)
If the inner macro (as given by \verb|\|\meta{internal cs name}) contains
non-expandable commands then you may need to redefine
\cs{gls}\meta{internal cs name}\texttt{page} after using
\cs{glsaddprotectedpagefmt}\marg{internal cs name}. This command doesn't take any arguments
-as the location is assumed to be given by \cs{c@page}. For example,
+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]{%
@@ -5292,7 +6023,7 @@ 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 location list in the glossary
+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}
@@ -5307,18 +6038,22 @@ combined with
\GlsAddXdyLocation{romansc}{:sep "\string\textsc\glsopenbrace"
"roman-numbers-lowercase" :sep "\glsclosebrace"}
\end{verbatim}
-will now have lowercase Roman numerals in the location list.
-(This option may cause problems if your locations should be
-hyperlinks.)
+will now have lowercase Roman numerals in the location list
+(see \sectionref{sec:xindyloc} for further details on that command).
+Take care of the backslashes. The location (which ends up in
+the ":locref" attribute) needs \verb|\\| but the location class
+(identified with \cs{GlsAddXdyLocation}) just has a single
+backslash. Note that this example will cause problems if your
+locations should be hyperlinks.
-Another possibility that will work with both \gls{makeindex} and
+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 and redefine
+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}}
+\renewcommand*{\gls@samplenumpage}{\number\c@page}
+\renewcommand*{\glsnumberformat}[1]{\textsc{\romannumeral#1}}
\end{verbatim}
\begin{important}
@@ -5334,13 +6069,19 @@ 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.
+should be no range formation (see \sectionref{sec:xindyloc} for
+further details).
\begin{important}
Note that \cs{GlsSetXdyMinRangeLength} must be used before
@@ -5382,6 +6123,12 @@ 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]
@@ -5439,6 +6186,9 @@ which is described in \sectionref{sec:customxr}.
\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:
@@ -5468,21 +6218,22 @@ valid code.
\label{sec:glslink}
Once you have defined a glossary entry using \ics{newglossaryentry}
-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
+(\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 \opt1. If you don't use \ics{makeglossaries} these external
-files won't be created.
+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
@@ -5609,7 +6360,9 @@ other key that you plan to access through these commands.
\cs{glssymbol}.)
\end{important}
-The following keys are available for the optional argument:
+The keys listed below are available for the optional argument.
+The \gls{glossaries-extra} package provides additional keys.
+(See the \gls*{glossaries-extra} manual for further details.)
\begin{description}
\item[{\gloskey[glslink]{hyper}}] This is a boolean key which can
be used to enable\slash disable the hyperlink to the relevant entry
@@ -5628,22 +6381,28 @@ value is equivalent to the \gls{makeindex} encap value, and (as
with \ics{index}) the value needs to be the name of a command
\emph{without} the initial backslash. As with \ics{index}, the
characters \verb"(" and \verb")" can also be used to specify the
-beginning and ending of a number range. Again as with \ics{index},
-the command should be the name of a command which takes an argument
-(which will be the associated location). Be careful not to use a
-declaration (such as \texttt{bfseries}) instead of a text block command
-(such as \texttt{textbf}) as the effect is not guaranteed to be
-localised. If you want to apply more than one style to a given entry
-(e.g.\ \textbf{bold} and \emph{italic}) you will need to create a
-command that applies both formats, e.g.\
+beginning and ending of a number range and they must be in matching
+pairs. (For example, \verb|\gls[format={(}]{sample}| on one page
+to start the range and later \verb|\gls[format={)}]{sample}| to close
+the range.) Again as with \ics{index}, the command should be the
+name of a command which takes an argument (which will be the
+associated location). Be careful not to use a declaration (such as
+\texttt{bfseries}) instead of a text block command (such as
+\texttt{textbf}) as the effect is not guaranteed to be localised. If
+you want to apply more than one style to a given entry (e.g.\
+\textbf{bold} and \emph{italic}) you will need to create a command
+that applies both formats, e.g.\
\begin{verbatim}
\newcommand*{\textbfem}[1]{\textbf{\emph{#1}}}
\end{verbatim}
and use that command.
-In this document, the standard formats refer to the standard text
-block commands such as \ics{textbf} or \ics{emph} or any of the
-commands listed in \tableref{tab:hyperxx}.
+In this document, the standard formats refer to the standard text
+block commands such as \ics{textbf} or \ics{emph} or any of the
+commands listed in \tableref{tab:hyperxx}. You can combine a range
+and format using \verb|(|\meta{format} to start the range and
+\verb|)|\meta{format} to end the range. The \meta{format} part must
+match. For example, \verb|format={(emph}| and \verb|format={)emph}|.
\begin{important}
If you use \gls{xindy} instead of \gls{makeindex}, you
@@ -5695,9 +6454,9 @@ sans-serif font, you can define a command called, say,
\newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}}
\end{verbatim}
and then use \texttt{hyperbsf} as the value for the \gloskey{format}
-key. (See also \ifpdf section~\ref*{sec:code:printglos} \fi
+key.\footnote{See also \ifpdf section~\ref*{sec:code:printglos} \fi
\qt{Displaying the glossary} in the documented code,
-\texttt{glossaries-code.pdf}.) Remember that if you use \gls{xindy}, you
+\texttt{glossaries-code.pdf}.} Remember that if you use \gls{xindy}, you
will need to add this to the list of location attributes:
\begin{verbatim}
\GlsAddXdyAttribute{hyperbsf}
@@ -5714,9 +6473,6 @@ the \gls*{firstuseflag} will be localised to the current scope. The
default is \texttt{local=false}.
\end{description}
-The \gls{glossaries-extra} package provides an additional key.
-Please see the \gls{glossaries-extra} user manual for further
-details.
\begin{important}
The \gls{linktext} isn't scoped by default. Any unscoped
@@ -6772,7 +7528,8 @@ You must use \ics{makeglossaries} (\optsor23) or
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.
+entry definitions. The \gls{glossaries-extra} package provides
+better cross-reference handling.
\end{important}
There are several ways of cross-referencing entries in the
@@ -7289,7 +8046,9 @@ have directly used \gls{makeindex} or \gls{xindy} (as described in
\sectionref{sec:makeglossaries}). (While the external files are
missing, these commands will just do \cs{null} for each missing
glossary to assist dictionary style documents that just use
-\cs{glsaddall} without inserting any text.)
+\cs{glsaddall} without inserting any text. If you use
+\gls{glossaries-extra}, it will insert a heading and boilerplate text when the
+external files are missing.)
If the glossary still does not appear after you re-\LaTeX\ your
document, check the \gls*{makeindex}\slash\gls*{xindy} log files to
@@ -7511,9 +8270,11 @@ This ensures that the glossary information is written in
\gls*{xindy} syntax.
\sectionref{sec:makeglossaries} covers how to use the external
-\gls{indexingapp}. 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.
+\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
@@ -7701,8 +8462,8 @@ 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}.
-(See also \ics{glsaddprotectedpagefmt} described in
-\sectionref{sec:numberlists}.)
+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
@@ -7752,24 +8513,48 @@ This example is illustrated in the sample file
\samplefile{xdy2}.
\end{example}
-\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{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}
-\renewcommand*{\thepage}{\Numberstring{page}}
+newcommand{\tally}[1]{\tallynum{\arabic{#1}}}
\end{verbatim}
-This gets expanded to \verb|\protect \Numberstringnum |\marg{n}
-where \meta{n} is the Arabic page number. This means that I~need to
-define a new location that has that form:
+The \ctr{page} counter representation (\cs{thepage}) needs to be
+changed to use this command:
\begin{verbatim}
-\GlsAddXdyLocation{Numberstring}{:sep "\string\protect\space
- \string\Numberstringnum\space\glsopenbrace"
- "arabic-numbers" :sep "\glsclosebrace"}
+\renewcommand*{\thepage}{\tally{page}}
\end{verbatim}
-Note that it's necessary to use \cs{space} to indicate that
-spaces also appear in the format, since, unlike \TeX,
-\gls{xindy} doesn't ignore spaces after control sequences.
+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:
@@ -7779,16 +8564,16 @@ commands in the form:
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{the}\meta{Hcounter}
-is given by \cs{Hprefix}"."\cs{the}\meta{counter}. The sample
-file \samplefile{xdy}, which comes with the \styfmt{glossaries}
+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{Numberstring}, as
+format. A new \gls{xindy} location called \texttt{tallynum}, as
illustrated above, is defined to make the page numbers appear as
-\qt{One}, \qt{Two}, etc. In order for the location numbers to
+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}
@@ -7800,28 +8585,99 @@ hyperlink to the relevant pages, I~need to redefine the necessary
\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. The sample file
+\samplefile{xdy3} illustrates this.
\end{example}
-In the \gls{numberlist}, the locations are sorted according to
-type. The default ordering is: \texttt{roman-page-numbers} (e.g.\
-i), \texttt{arabic-page-numbers} (e.g.\ 1),
-\texttt{arabic-section-numbers} (e.g.\ 1.1 if the compositor is a
-full stop or 1-1 if the compositor is a hyphen\footnote{see
-\ics{setCompositor} described in \sectionref{sec:setup}}),
-\texttt{alpha-page-numbers} (e.g.\ a), \texttt{Roman-page-numbers}
-(e.g.\ I), \texttt{Alpha-page-numbers} (e.g.\ A),
-\texttt{Appendix-page-numbers} (e.g.\ A.1 if the Alpha compositor is
-a full stop or A-1 if the Alpha compositor is a hyphen\footnote{see
-\ics{setAlphaCompositor} described in
-\sectionref{sec:setup}}), user defined location names (as
-specified by \ics{GlsAddXdyLocation} in the order in which they were
-defined), \texttt{see} (cross-referenced entries). This ordering can
-be changed using:
-
-\DescribeMacro{\GlsSetXdyLocationClassOrder}
-\begin{definition}
+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
@@ -7838,6 +8694,8 @@ separated by white space. For example:
"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
@@ -7849,10 +8707,9 @@ Note that \cs{GlsSetXdyLocationClassOrder} has no effect if
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:\newpage
+defaults to 2, but can be changed using:
-\DescribeMacro{\GlsSetXdyMinRangeLength}
-\begin{definition}
+\begin{definition}[\DescribeMacro\GlsSetXdyMinRangeLength]
\cs{GlsSetXdyMinRangeLength}\marg{n}
\end{definition}
For example:
@@ -7869,8 +8726,7 @@ is used or if \ics{makeglossaries} is omitted.
\cs{GlsSetXdyMinRangeLength} must be used before
\ics{makeglossaries}.
\end{important}
-
-See \sectionref{sec:numberlists} for further details.
+See also \sectionref{sec:ranges}.
\section{Glossary Groups}
\label{sec:groups}
@@ -7883,24 +8739,55 @@ a number group by default, unless you suppress it in the
\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.
+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 have a number group, the default behaviour is to locate
-it before the \qt{A} letter group. If you are not using a
-Roman alphabet, you can change this using:
+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:
-\DescribeMacro{\GlsSetXdyFirstLetterAfterDigits}
-\begin{definition}
+
+\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 \cs{GlsSetXdyFirstLetterAfterDigits} has no effect if
+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}
@@ -8700,9 +9587,7 @@ since the description needs to be specified by the user.
It may be that you want to define a new acronym style that's based
on an existing style. Within \meta{display} you can use
-\par
-\DescribeMacro{\GlsUseAcrEntryDispStyle}
-\begin{definition}
+\begin{definition}[\DescribeMacro\GlsUseAcrEntryDispStyle]
\cs{GlsUseAcrEntryDispStyle}\marg{style name}
\end{definition}
to use the \meta{display} definition from the style given by
@@ -9919,6 +10804,10 @@ given entry by placing \ics{nopostdesc} in the entry's description.
As from version 3.03 you can now use the package option
\pkgopt{nopostdot} to suppress this full stop. This is the better
option if you want to use the \sty{glossaries-extra} package.
+The \sty{glossaries-extra-stylemods} package provides some
+adjustments some of to the predefined styles listed here, allowing
+for greater flexibility. See the \sty{glossaries-extra}
+documentation for further details.
\subsection{List Styles}
\label{sec:liststyles}
@@ -9932,7 +10821,9 @@ these styles will automatically be available unless you use the
\begin{important}
Note that, except for the \glostyle{listdotted} style, these
-list styles are incompatible with \sty{classicthesis}.
+list styles are incompatible with \sty{classicthesis}. They
+may also be incompatible with other classes or packages that
+modify the \env{description} environment.
\end{important}
\begin{description}
@@ -11765,8 +12656,7 @@ non-empty value for the \gloskey{prefixplural} key.
Does \meta{true part} if the entry identified by \meta{label} has a
non-empty value for the \gloskey{prefixfirst} key.
-\DescribeMacro\ifglshasprefixfirstplural
-\begin{definition}
+\begin{definition}[\DescribeMacro\ifglshasprefixfirstplural]
\cs{ifglshasprefixfirstplural}\marg{label}\marg{true part}\marg{false part}
\end{definition}
Does \meta{true part} if the entry identified by \meta{label} has a
@@ -11791,8 +12681,7 @@ Displays the value of the \gloskey{prefixplural} key for the entry given
by \meta{label}. (No check is performed to determine if the entry
exists.)
-\DescribeMacro\glsentryprefixfirstplural
-\begin{definition}
+\begin{definition}[\DescribeMacro\glsentryprefixfirstplural]
\cs{glsentryprefixfirstplural}\marg{label}
\end{definition}
Displays the value of the \gloskey{prefixfirstplural} key for the entry given
@@ -11812,8 +12701,7 @@ apply.}:
\cs{Glsentryprefixplural}\marg{label}
\end{definition}
-\DescribeMacro\Glsentryprefixfirstplural
-\begin{definition}
+\begin{definition}[\DescribeMacro\Glsentryprefixfirstplural]
\cs{Glsentryprefixfirstplural}\marg{label}
\end{definition}
@@ -11907,7 +12795,8 @@ that you also read the \sty{accsupp} documentation.
\chapter{Troubleshooting}
\label{sec:trouble}
-The \styfmt{glossaries} package comes with some minimal example
+In addition to the sample files listed in \sectionref{sec:samples},
+the \styfmt{glossaries} package comes with some minimal example
files, \texttt{minimalgls.tex}, \texttt{mwe-gls.tex},
\texttt{mwe-acr.tex} and \texttt{mwe-acr-desc.tex}, which can be
used for testing. These should be located in the \texttt{samples}
@@ -11916,6 +12805,8 @@ directory. The location varies according to your operating system
and \TeX\ installation. For example, on my Linux partition it can
be found in \texttt{/usr\slash local\slash texlive\slash
2014\slash texmf-dist\slash doc\slash latex\slash glossaries/}.
+The \gls{makeglossariesgui} application can also be used to test for
+various problems.
Further information on debugging \LaTeX\ code is available at
\url{http://www.dickimaw-books.com/latex/minexample/}.