diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex |
Initial commit
Diffstat (limited to 'macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r-- | macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex | 12125 |
1 files changed, 12125 insertions, 0 deletions
diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex new file mode 100644 index 0000000000..674b704722 --- /dev/null +++ b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex @@ -0,0 +1,12125 @@ +\documentclass[report,inlinetitle,widecs]{nlctdoc} + +\makeatletter +\@ifpackageloaded{tex4ht} +{ + \DeclareUnicodeCharacter{00FE}{\HCode{&\#x00FE;}} + \DeclareUnicodeCharacter{00D0}{\HCode{&\#x00D0;}} + \DeclareUnicodeCharacter{01F7}{\HCode{&\#x01F7;}} + \DeclareUnicodeCharacter{A77D}{\HCode{&\#xA77D;}} + \DeclareUnicodeCharacter{017F}{\HCode{&\#x017F;}} + \DeclareUnicodeCharacter{018F}{\HCode{&\#x018F;}} +} +{ + \usepackage{fontspec} + \setmainfont{FreeSerif} +} +\makeatother + +\usepackage{alltt} +\usepackage{hologo} +\usepackage[colorlinks, + hyperindex=false, + pdfauthor={Nicola L.C. Talbot}, + pdftitle={glossaries-extra.sty: an extension to the glossaries +package}, + pdfkeywords={LaTeX,package,glossary,abbreviations}]{hyperref} +\usepackage[nogroupskip,nonumberlist]{glossaries-extra} + +\makeglossaries + +\GlsXtrEnableEntryUnitCounting{general}{0}{page} + +\renewcommand*{\glsxtrifcounttrigger}[3]{#3} + +\renewcommand*{\glslinkcheckfirsthyperhook}{% + \ifnum\glsentrycurrcount\glslabel>0 + \setkeys{glslink}{hyper=false}% + \fi +} + +\newcommand*{\XeLaTeX}{\hologo{XeLaTeX}} +\newcommand*{\LuaLaTeX}{\hologo{LuaLaTeX}} +\newcommand*{\pdfLaTeX}{\hologo{pdfLaTeX}} + +\IndexPrologue{\chapter*{\indexname} + \addcontentsline{toc}{chapter}{\indexname}% + \markboth{\indexname}{\indexname}} + +\renewcommand*{\main}[1]{\hyperpage{#1}} +\newcommand*{\htextbf}[1]{\textbf{\hyperpage{#1}}} + +\glssetcategoryattribute{general}{indexname}{htextbf} +\glssetcategoryattribute{general}{dualindex}{main} + +\newglossaryentry{xindy}{ + name={\appfmt{xindy}}, + sort={xindy}, + description={An flexible indexing application with multilingual + support written in Perl.} +} + +\newglossaryentry{makeindex}{% + name={\appfmt{makeindex}},% + sort={makeindex},% + description={An indexing application.}, +} + +\newglossaryentry{makeglossaries}{% +name={\appfmt{makeglossaries}},% +sort={makeglossaries},% +description={A custom designed Perl script interface +provided with the \styfmt{glossaries} package +to run \gls{xindy} or \gls{makeindex} according to +the document settings.}} + +\newglossaryentry{makeglossaries-lite.lua}{% +name={\appfmt{makeglossaries-lite}\index{makeglossaries-lite=\appfmt{makeglossaries-lite}|htextbf}},% +sort={makeglossaries-lite},% +text={\appfmt{makeglossaries-lite}\iapp{makeglossaries-lite}},% +description={A custom designed Lua script interface +to \gls{xindy} and \gls{makeindex} provided with the +\styfmt{glossaries} +package. This is a cut-down alternative to the Perl +\appfmt{makeglossaries} script. If you have Perl installed, use the +Perl script instead. This script is distributed in the source code +on CTAN 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, and +\TeX\ distributions on Windows convert the script to an executable +\texttt{makeglossaries-lite.exe}.} +} + +\newglossaryentry{bib2gls}{% +name={\appfmt{bib2gls}},% +sort={bib2gls},% +description={A command line Java application that selects +entries from a .bib file and converts them to glossary +definitions (like \appfmt{bibtex} but also performs hierarchical +sorting and collation, thus omitting the need for \gls{xindy} or +\gls{makeindex}). Further details at: +\url{http://www.dickimaw-books.com/software/bib2gls/}.}% +} + +\newglossaryentry{numberlist}{% +name={number list},% +description={A list of \glspl{entrylocation} (also +called a location list). The number list can be suppressed using the +\pkgopt{nonumberlist} package option.} +} + +\newglossaryentry{entrylocation}{% +name={entry location},% +description={The location of the entry in the document. This +defaults to the page number on which the entry appears. An entry may +have multiple locations.} +} + +\newglossaryentry{locationlist}{% +name={location list},% +description={A list of \glspl{entrylocation}. +See \gls{numberlist}.}% +} + +\newglossaryentry{linktext}{% +name={link-text}, +description={The text produced by commands such as \ics{gls}. It may +or may not have a hyperlink to the glossary.} +} + +\let\glsd\glsuseri +\let\glsation\glsuserii + +\newglossaryentry{firstuseflag}{% +name={first use flag}, +description={A conditional that determines whether or not the entry +has been used according to the rules of \gls{firstuse}.}% +} + +\newglossaryentry{firstusetext}{% +name={first use text}, +description={The text that is displayed on \gls{firstuse}, which is +governed by the \gloskey{first} and \gloskey{firstplural} keys of +\ics{newglossaryentry}. (May be overridden by +\ics{glsdisp}.)}% +} + +\newglossaryentry{firstuse}{% + name={first use}, + user1={first used}, + see={firstuseflag,firstusetext}, + description={The first time a glossary entry is used (from the start + of the document or after a reset) with one of the + following commands: \ics{gls}, \ics{Gls}, \ics{GLS}, \ics{glspl}, + \ics{Glspl}, \ics{GLSpl} or \ics{glsdisp}.}% +} + +\setcounter{IndexColumns}{2} + +\newrobustcmd*{\eq}{\protect=}% hide from makeindex + +\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}} +\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}} +\newcommand*{\optfmt}[1]{\textsf{#1}} + +\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\sffamily#1}|main}} + +\newcommand*{\acrstyle}[1]{\textsf{#1}\index{acronym +styles (glossaries):>#1={\protect\ttfamily#1}|main}} + +\newcommand*{\abbrstylenolink}[1]{% + \textsf{#1}\index{abbreviation styles:>#1={\protect\sffamily#1}|main}} + +\newcommand*{\abbrstyle}[1]{% + \hyperlink{abbrstyle.#1}{\textsf{#1}}% + \index{abbreviation styles:>#1={\protect\sffamily#1}|main}% +} + +\makeatletter +\newcommand{\htarget}[2]{\Hy@raisedlink{\hypertarget{#1}{}}#2} +\makeatother + +\newcommand*{\abbrstyledef}[1]{% + \htarget{abbrstyle.#1}{\textsf{#1}}% + \index{abbreviation styles:>#1={\protect\sffamily#1}|main}% +} + +\newcommand*{\depabbrstyle}[1]{\textsf{#1}\index{abbreviation styles (deprecated):>#1={\protect\sffamily#1}|main}} + +\newcommand*{\category}[1]{\textsf{#1}\index{categories:>#1={\protect\sffamily#1}|main}} + +\newcommand*{\catattrnolink}[1]{% + \textsf{#1}\index{category attributes:>#1={\protect\sffamily#1}|main}} + +\newcommand*{\catattr}[1]{% + \hyperlink{catattr.#1}{\textsf{#1}}% + \index{category attributes:>#1={\protect\sffamily#1}|main}% +} + +\newcommand*{\catattrdef}[1]{% + \htarget{catattr.#1}{\textsf{#1}}% + \index{category attributes:>#1={\protect\sffamily#1}|main}% +} + +\newcommand*{\postlinkcat}{% + \cs{glsxtrpostlink}\meta{category}% + \index{glsxtrpostlinkcategory=\cs{glsxtrpostlink}\meta{category}|hyperpage}% +} + +\renewcommand*{\pkgopt}[2][]{% + \hyperlink{styopt.#2}{\pkgoptfmt{#2}}% + \ifstrempty{#1}{}{\pkgoptfmt{=#1}}% + \ipkgopt[#1]{#2}% +} + +\newcommand*{\pkgoptdef}[1]{% + \htarget{styopt.#1}{\pkgoptfmt{#1}}% + \ipkgopt{#1}% +} + +\setlength\marginparwidth{70pt} + +\begin{document} +\DeleteShortVerb{\|} +\MakeShortVerb{"} + + \title{glossaries-extra.sty v1.41: + an extension to the glossaries package} + \author{Nicola L.C. Talbot\\[10pt] +Dickimaw Books\\ +\url{http://www.dickimaw-books.com/}} + + \date{2019-04-09} + \maketitle + +\begin{abstract} +The \styfmt{glossaries-extra} package is an extension to the +\styfmt{glossaries} package, providing additional features. +Some of the features provided by this package are only available +with \styfmt{glossaries} version 4.19 (or above). +This document assumes familiarity with the \styfmt{glossaries} package. + +The file \texttt{example-glossaries-xr.tex} contains dummy +entries with cross-references that may be used for creating +minimal working examples for testing the \styfmt{glossaries-extra} +package. (The base \styfmt{glossaries} package provides additional files, +but this one needs \styfmt{glossaries-extra}.) There are equivalent +\texttt{.bib} files for use with \gls{bib2gls}. + +\end{abstract} + +\begin{important} +Since \styfmt{glossaries-extra} internally loads the \styfmt{glossaries} +package, you also need to have \styfmt{glossaries} installed and +all the packages that \styfmt{glossaries} depends on (including, but +not limited to, \sty{tracklang}, \sty{mfirstuc}, \sty{etoolbox}, +\sty{xkeyval} (at least version dated 2006/11/18), \sty{textcase}, +\sty{xfor}, \sty{datatool-base} and \sty{amsgen}. These +packages are all available in the current \TeX\ Live and Mik\TeX\ +distributions. If any of them are missing, please update your +\TeX\ distribution using your update manager. +(For help on this see, for example, +\href{http://tex.stackexchange.com/questions/55437/how-do-i-update-my-tex-distribution}{How do I update my \TeX\ distribution?} +or +\href{http://tex.stackexchange.com/questions/14925/updating-tex-on-linux}{Updating +\TeX\ on Linux}.) +\end{important} + +Additional resources: +\begin{itemize} +\item The \styfmt{glossaries-extra} documented code +\href{http://mirrors.ctan.org/macros/latex/contrib/glossaries-extra/glossaries-extra-code.pdf}{glossaries-extra-code.pdf}. + +\item The +\href{http://www.dickimaw-books.com/gallery/#glossaries-extra}{\styfmt{glossaries-extra} gallery}. + +\item \styfmt{glossaries-extra} and \gls{bib2gls}: An Introductory +Guide. (\href{http://mirrors.ctan.org/support/bib2gls/bib2gls-begin.pdf}{\texttt{bib2gls-begin.pdf}}). + +\item +\href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating +makeglossaries or makeglossaries-lite or bib2gls into the document +build}. + +\item The +\href{http://www.dickimaw-books.com/software/bib2gls}{\appfmt{bib2gls}} +application. + +\item The base \href{https://ctan.org/pkg/glossaries}{\styfmt{glossaries}} package. +\end{itemize} + +\tableofcontents + +\chapter{Introduction} +\label{sec:intro} + +The \styfmt{glossaries} package is a flexible package, but it's also a +heavy-weight package that uses a lot of resources. As package +developer, I'm caught between those users who complain about the +drawbacks of a heavy-weight package with a large user manual and +those users who want more features (which necessarily adds to the +package weight and manual size). + +The \styfmt{glossaries-extra} package is an attempt to provide +a~compromise for this +conflict. Version 4.22 of the \styfmt{glossaries} package is +the last version to incorporate new features.\footnote{4.21 was +originally intended as the last release of \styfmt{glossaries} to +incorporate new features, but a few new minor features slipped in with +some bug fixes in v4.21.} Future versions of +\styfmt{glossaries} will just be bug fixes. New features will +instead be added to \styfmt{glossaries-extra}. +This means that the base \styfmt{glossaries} package won't increase +in terms of package loading time and allocation of resources, but +those users who do want extra features available will have more of a +chance of getting their feature requests accepted. + +\section{Package Defaults} +\label{sec:defaults} + +I'm not happy with some of the default settings assumed by the +\styfmt{glossaries} package, and, judging from code I've seen, other +users also seem unhappy with them, as certain package options are +often used in questions posted on various sites. I can't change the default +behaviour of \styfmt{glossaries} as it would break backward +compatibility, but since \styfmt{glossaries-extra} is a separate +package, I have decided to implement some of these commonly-used +options by default. You can switch them back if they're not +appropriate. + +The new defaults are: +\begin{itemize} +\item \pkgopt[true]{toc} (add the glossaries to the table of +contents). Use \pkgopt[false]{toc} to switch this back off. + +\item \pkgopt[true]{nopostdot} (suppress the terminating full stop +after the description in the glossary). Use +\pkgopt[false]{nopostdot} or just \pkgopt{postdot} to restore the +terminating full stop (period). + +\item \pkgopt[true]{noredefwarn} (suppress the warnings that occur when +the \env{theglossary} environment and \cs{printglossary} are redefined while +\styfmt{glossaries} is loading). To restore the warnings, use +\pkgopt[false]{noredefwarn}. Note that this won't have any effect if +the \styfmt{glossaries} package has already been loaded before you use +the \styfmt{glossaries-extra} package. + +\item If \sty{babel} has been loaded, the \pkgopt[babel]{translate} +option is switched on. To revert to using the \sty{translator} +interface, use \pkgopt[true]{translate}. There is no change to the +default if \sty{babel} hasn't been loaded. + +\end{itemize} + +The examples below illustrate the difference in explicit +package options between \styfmt{glossaries} and +\styfmt{glossaries-extra}. There may be other differences +resulting from modifications to commands provided by +\styfmt{glossaries} (see \sectionref{sec:modifications}). + +\begin{enumerate} +\item +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries-extra} +\end{verbatim} +This is like: +\begin{verbatim} +\documentclass{article} +\usepackage[toc,nopostdot]{glossaries} +\usepackage{glossaries-extra} +\end{verbatim} + +\item +\begin{verbatim} +\documentclass[british]{article} +\usepackage{babel} +\usepackage{glossaries-extra} +\end{verbatim} +This is like: +\begin{verbatim} +\documentclass[british]{article} +\usepackage{babel} +\usepackage[toc,nopostdot,translate=babel]{glossaries} +\usepackage{glossaries-extra} +\end{verbatim} + +\item +\begin{verbatim} +\documentclass{memoir} +\usepackage{glossaries-extra} +\end{verbatim} +This is like: +\begin{verbatim} +\documentclass{memoir} +\usepackage[toc,nopostdot,noredefwarn]{glossaries} +\usepackage{glossaries-extra} +\end{verbatim} +\emph{However} +\begin{verbatim} +\documentclass{memoir} +\usepackage{glossaries} +\usepackage{glossaries-extra} +\end{verbatim} +This is like: +\begin{verbatim} +\documentclass{memoir} +\usepackage[toc,nopostdot]{glossaries} +\usepackage{glossaries-extra} +\end{verbatim} +Since by the time \styfmt{glossaries-extra} has been loaded, +\styfmt{glossaries} has already redefined \cls{memoir}'s +glossary-related commands. +\end{enumerate} + +Another noticeable change is that by default \cs{printglossary} +will now display information text in the document if the external +glossary file doesn't exist. This is explanatory text to help new +users who can't work out what to do next to complete the document +build. Once the document is set up correctly and the external files +have been generated, this text will disappear. + +This change is mostly likely to be noticed by users +with one or more redundant empty glossaries who ignore +transcript messages, explicitly use \gls{makeindex}\slash\gls{xindy} +on just the non-empty glossary (or glossaries) and use +the iterative +\ics{printglossaries} command instead of \ics{printglossary}. For example, +consider the following: +\begin{verbatim} +\documentclass{article} + +\usepackage[acronym]{glossaries} + +\makeglossaries + +\newacronym{laser}{laser}{light amplification by stimulated +emission of radiation} + +\begin{document} + +\gls{laser} + +\printglossaries + +\end{document} +\end{verbatim} +The above document will only display the list of +acronyms at the place where \ics{printglossaries} occurs. However it +will also attempt to input the \texttt{.gls} file associated with +the \texttt{main} glossary. + +If you use \gls{makeglossaries}, you'll get the warning message: +\begin{verbatim} +Warning: File 'test.glo' is empty. +Have you used any entries defined in glossary 'main'? +Remember to use package option 'nomain' if you +don't want to use the main glossary. +\end{verbatim} +(where the original file is called \texttt{test.tex}) +but if you simply call \gls{makeindex} directly to generate the +\texttt{.acr} file (without attempting to create the \texttt{.gls} +file) then the transcript file will always contain the message: +\begin{verbatim} +No file test.gls. +\end{verbatim} +This doesn't occur with \gls{makeglossaries} as it will create +the \texttt{.gls} file containing the single command \cs{null}. + +If you simply change from \styfmt{glossaries} to +\styfmt{glossaries-extra} in this document, you'll find a change in the +resulting PDF if you don't use \gls{makeglossaries} and you only +generate the \texttt{.acr} file with \gls{makeindex}. + +The transcript file will still contain the message +about the missing \texttt{.gls}, but now you'll also see +information in the actual PDF document. The simplest remedy is to +follow the advice inserted into the document at that point, which is +to add the \pkgopt{nomain} package option: +\begin{verbatim} +\documentclass{article} + +\usepackage[nomain,acronym,postdot]{glossaries-extra} + +\makeglossaries + +\setabbreviationstyle[acronym]{long-short} + +\newacronym{laser}{laser}{light amplification by stimulated +emission of radiation} + +\begin{document} + +\gls{laser} + +\printglossaries + +\end{document} +\end{verbatim} +(Note the need to set the acronym style using +\cs{setabbreviationstyle} before \cs{newacronym}. +See \sectionref{sec:abbreviations} for further details.) + +\section{New or Modified Package Options} +\label{sec:pkgopts} + +If you haven't already loaded \styfmt{glossaries}, you can use any of +the package options provided by \styfmt{glossaries} when you load +\styfmt{glossaries-extra} and they will automatically be passed to +\styfmt{glossaries} (which \styfmt{glossaries-extra} will load). If +\styfmt{glossaries} has already been loaded, then those options will be +passed to \ics{setupglossaries}, but remember that not all of the +\styfmt{glossaries} package options may be used in that command. + +\begin{important} +This section only lists options that are either unrecognised by +the \styfmt{glossaries} package or are a modified version of options +of the same name provided by \styfmt{glossaries}. See the +\styfmt{glossaries} user manual for details about the unmodified +options. +\end{important} + +The new and modified options provided by \styfmt{glossaries-extra} +are described below: + +\begin{description} + +\item[{\pkgoptdef{debug}}] The \styfmt{glossaries} package +has a \pkgoptfmt{debug} option that allows the values +\pkgoptfmt{false}, \pkgoptfmt{true} and \pkgoptfmt{showtargets}. +The \pkgopt[showtargets]{debug} option was introduced to +\styfmt{glossaries} v4.32, so if you want to use this option +with \styfmt{glossaries-extra} you must make sure that +your version of \styfmt{glossaries} supports it. + +The \styfmt{glossaries-extra} package extends this option +to provide the additional values \pkgopt[showwrgloss]{debug} +and \pkgopt[all]{debug}. + +The \pkgopt[showwrgloss]{debug} option implements +\pkgopt[true]{debug} and uses +\begin{definition}[\DescribeMacro\glsxtrwrglossmark] +\cs{glsxtrwrglossmark} +\end{definition} +to show a mark \ensuremath{\cdot} just before the write operation +performed by the indexing commands. If you use +\pkgopt[alsoindex]{record} there will be a mark for the +write operation to the \texttt{.aux} file for \gls{bib2gls} +and a mark for the write operation to the associated glossary +file for \gls{makeindex} or \gls{xindy}. + +The \pkgopt[all]{debug} option implements both \pkgopt[showtargets]{debug} +and \pkgopt[showwrgloss]{debug}. + +\item[{\pkgoptdef{postdot}}] (New to version 1.12.) +This option is just a shortcut for \pkgopt[false]{nopostdot}. + +\item[{\pkgoptdef{postpunc}}] (New to version 1.21.) +This option sets the post-description punctuation to the given +value. For example: \pkgoptfmt{postpunc={;}} does +\begin{verbatim} +\renewcommand{\glspostdescription}{;} +\end{verbatim} +The value may also be one of the following keywords: +\begin{description} +\item[\texttt{comma}:] \pkgopt[comma]{postpunc} is +equivalent to +\begin{verbatim} +\renewcommand{\glspostdescription}{,} +\end{verbatim} + +\item[\texttt{dot}:] \pkgopt[dot]{postpunc} is +equivalent to +\begin{verbatim} +\renewcommand{\glspostdescription}{.\spacefactor\sfcode`\. } +\end{verbatim} + +\item[\texttt{none}:] \pkgopt[none]{postpunc} is +equivalent to +\begin{verbatim} +\renewcommand{\glspostdescription}{} +\end{verbatim} +\end{description} +The default definition is +\begin{verbatim} +\newcommand*{\glspostdescription}{% + \ifglsnopostdot\else.\spacefactor\sfcode`\. \fi +} +\end{verbatim} +where the conditional is determined by the \pkgopt{nopostdot} +package option. The \pkgopt{postpunc} option removes the conditional +from the definition of \cs{glspostdescription}. The package options +\pkgopt{nopostdot} and \pkgopt{postdot} will restore the original definition of +\cs{glspostdescription}. + +The \sty{glossaries-extra-stylemods} package adjusts +the predefined styles that had a hard-coded \cs{space} +before the \gls{numberlist} so that they use \cs{glsxtrprelocation} +instead (which is defined to \cs{space}). You can therefore +redefine this command in combination with \pkgopt{postpunc} +to alter the separator before the \gls{numberlist}. +For example, to have a comma followed by \cs{hfil}: +\begin{verbatim} +\usepackage[postpunc=comma,stylemods]{glossaries-extra} +\renewcommand{\glsxtrprelocation}{\hfil} +\end{verbatim} +Be careful with doing this as it will look odd if the \gls{numberlist} is +missing. (With \gls{bib2gls} you can instead redefine +\cs{glsxtrprelocation} to do nothing and set the +location prefixes with \texttt{loc-prefix} which will only +apply if the entry has a \gls{numberlist}.) + +\item[{\pkgoptdef{accsupp}}] Load the \sty{glossaries-accsupp} +package (if not already loaded). + +If you want to define styles that can interface with the +accessibility support provided by \sty{glossaries-accsupp} use +the \cs{glsaccess\meta{xxx}} type of commands instead of +\cs{glsentry\meta{xxx}} (for example, \ics{glsaccesstext} instead of +\ics{glsentrytext}). If \sty{glossaries-accsupp} hasn't been loaded +those commands are equivalent (for example, \cs{glsaccesstext} +just does \cs{glsentrytext}) but if it has been loaded, then the +\cs{glsaccess\meta{xxx}} commands will add the accessibility +information. (See \sectionref{sec:accsupp} for further details.) + +Note that the \pkgopt{accsupp} option can only be used as +a~package option (and can't be set with \ics{glossariesextrasetup}) since the \sty{glossaries-accsupp} +package must be loaded before \styfmt{glossaries-extra} if it's +required. + +\item[{\pkgoptdef{stylemods}}] This is a +\meta{key}=\meta{value} option used to load the +\sty{glossaries-extra-stylemods} package. The value may be a +comma-separated list of options to pass to that package. (Remember +to group \meta{value} if it contains any commas.) The value may be +omitted if no options need to be passed. See \sectionref{sec:glosstylemods} +for further details. There are two special keyword values: +\pkgopt[default]{stylemods} (equivalent to omitting the value) +and \pkgopt[all]{stylemods}, which loads all the +predefined styles. + +\item[{\pkgoptdef{undefaction}}] This is a \meta{key}=\meta{value} +option, which has two allowed values: \pkgoptfmt{warn} and +\pkgoptfmt{error}. This indicates what to do if an undefined +glossary entry is referenced. The default behaviour is +\pkgopt[error]{undefaction}, which produces an error message (the +default for \styfmt{glossaries}). You can switch this to a warning +message (and ?? appearing in the text) with +\pkgopt[warn]{undefaction}. + +\begin{important} +Undefined entries can't be picked up by any commands that iterate +over a glossary list. This includes \ics{forglsentries} and +\ics{glsaddall}. +\end{important} + +Note that \ics{ifglsused} will display ?? in the document text with +\pkgopt[warn]{undefaction} if the entry hasn't been defined, as the +underlying boolean variable doesn't exist and so is neither true nor +false. (There will also be a warning in the transcript.) See +\sectionref{sec:glsunset} for further details. + +\item[{\pkgoptdef{indexcrossrefs}}] This is a boolean option. +If \pkgoptfmt{true}, this will automatically index any +cross-referenced entries that haven't been marked as used at +the end of the document. Note that this necessarily adds to +the overall document build time, especially if you have defined +a large number of entries, so this defaults to \pkgoptfmt{false}, +but it will be automatically switched on if you use the \gloskey{see} +or \gloskey{seealso} keys in any entries (unless +\pkgopt[false]{autoseeindex}). To force it off, even if you use the +\gloskey{see} or \gloskey{seealso} key, you +need to explicitly set \pkgopt{indexcrossrefs} to \pkgoptfmt{false}. + +Note that \gls{bib2gls} can automatically find dependent +entries when it parses the \texttt{.bib} source file. +The \pkgopt{record} option automatically implements +\pkgopt[false]{indexcrossrefs}. + +\item[{\pkgoptdef{autoseeindex}}]\label{opt:autoseeindex} (New to +v1.16.) This is a boolean option. If true (default), this makes +the \gloskey{see} and \gloskey{seealso} keys automatically index the +cross-reference when an entry is defined. If false, the value +of those keys will still be stored in their corresponding fields +(and can be accessed using commands like \cs{glsxtrusesee} and +\cs{glsxtruseseealso}) but cross-reference won't be automatically +indexed. + +Note that the \pkgopt[only]{record} option automatically implements +\pkgopt[false]{autoseeindex}. + +For example, if an entry is defined as +\begin{verbatim} +\newglossaryentry{foo}{name={foo},description={},see={bar,baz}} +\end{verbatim} +then with \texttt{autoseeindex=true}, this is equivalent to +\begin{verbatim} +\newglossaryentry{foo}{name={foo},description={}} +\glssee{foo}{bar,baz} +\glossariesextrasetup{indexcrossrefs=true} +\GlsXtrSetField{foo}{see}{bar,baz} +\end{verbatim} +but with \texttt{autoseeindex=false}, this is equivalent to +\begin{verbatim} +\newglossaryentry{foo}{name={foo},description={}} +\GlsXtrSetField{foo}{see}{bar,baz} +\end{verbatim} +Note that \pkgopt{indexcrossrefs} isn't automatically implemented +by the presence of the \gloskey{see} key when \pkgopt{autoseeindex} +is false. + +It's therefore possible to remove the cross-references from the +location lists and set their position within the glossary style. + +Another method of preventing the automatic indexing is to +define the entries before the external indexing files have been +opened with \cs{makeglossaries}. Since the appropriate file isn't +open, the information can't be written to it. This will need +the package option \pkgoptfmt{seenoindex=ignore} (provided by +\styfmt{glossaries}) to prevent an error occurring. + +\item[{\pkgoptdef{record}}]\label{opt:record}(New to v1.08.) This is +a \meta{key}=\meta{value} option provided for the benefit of +\gls{bib2gls} (see \sectionref{sec:bib2gls}). + +The option may only be set in the preamble and can't be used after +\cs{GlsXtrLoadResources}. If the value is missing +\pkgopt[only]{record} is assumed. Permitted values: +\begin{description} +\item[\pkgoptfmt{off}] This is the default setting. The indexing +is performed as normal using either \cs{makeglossaries} +or \cs{makenoidxglossaries}. This setting implements \pkgopt[error]{undefaction}. + +\item[\pkgoptfmt{only}] The indexing is performed by +\gls{bib2gls} (see \sectionref{sec:bib2gls}). Neither +\cs{makeglossaries} nor \cs{makenoidxglossaries} is permitted. +This setting implements \pkgopt[warn]{undefaction} and automatically +loads the supplementary \sty{glossaries-extra-bib2gls} package. +(There should be no need to explicitly load \sty{glossaries-extra-bib2gls}.) + +The glossaries should be displayed using \cs{printunsrtglossary} +(or \cs{printunsrtglossaries}). + +The document build process is (assuming the file is called +\texttt{myDoc.tex}): +\begin{verbatim} +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +\end{verbatim} + +Note that \pkgopt[only]{record} will prevent the \gloskey{see} from +automatically implementing \cs{glssee}. (\gls{bib2gls} deals with the +\gloskey{see} field.) You may explicitly use \cs{glssee} in the +document, but \gls{bib2gls} will ignore the cross-reference if the +\gloskey{see} field was already set for that entry. + +The \pkgopt[only]{record} option will automatically set +the \styfmt{glossaries} package's \pkgopt[none]{sort} option +if available. (That option value was only introduced to +\styfmt{glossaries} v4.30.) + +\item[\pkgoptfmt{nameref}] (New to v1.37 and requires \gls{bib2gls} +v1.8+.) This option is like \pkgopt[only]{record} but additionally +records the current label information given by \cs{@currentlabel} +and \cs{@currentHref}, and provides a more reliable way of saving +the \cs{theH}\meta{counter} for the given location. This option +requires \sty{hyperref} otherwise it will fall back on the usual +location records. Remember that \cs{@currentHref} is always globally +updated whenever \cs{refstepcounter} is used, but \cs{@currentlabel} +isn't. This can cause some undesired side-effects with some settings. Remember also that the \pkgopt{indexcounter} option +increments the associated counter every time an entry is indexed, +which affects this option. See \sectionref{sec:recordnameref} for +further details. + +This option is best used with \pkgopt[chapter]{counter} or +\pkgopt[section]{counter} if you want the title included in the +location list. If the indexing counter is the default +\ctr{page}, only the location number is shown. Similarly for +\pkgopt[equation]{counter} (or \pkgopt[true]{equations}). + +\item[\pkgoptfmt{alsoindex}] This is a hybrid setting +that uses \gls{bib2gls} to fetch entry information from +\texttt{.bib} files, but uses \gls{makeindex} or \gls{xindy} +to create the glossary files. This option should be used +with \cs{makeglossaries} but not with its optional argument. +This option should not be used with \cs{makenoidxglossaries}. +You may need to change the transcript file used by \gls{bib2gls} +to avoid a clash with the transcript file used by +\gls{makeindex} or \gls{xindy}. (This can be done with +\gls{bib2gls}['s] \verb|--log-file| or \verb|-t| option.) + +The glossaries should be displayed using \cs{printglossary} +(or \cs{printglossaries}). This option is expected to be used with +\gls{bib2gls}'s \texttt{sort=none} setting and so +\sty{glossaries-extra-bib2gls} is not automatically loaded. + +The document build process is (assuming the file is called +\texttt{myDoc.tex}): +\begin{verbatim} +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +makeglossaries myDoc +pdflatex myDoc +\end{verbatim} +\end{description} + +With the recording on (\pkgopt[only]{record} or +\pkgopt[alsoindex]{record}), any of the commands that would typically +index the entry (such as \cs{gls}, \cs{glstext} or \cs{glsadd}) +will add a \cs{glsxtr@record} entry to the \texttt{.aux} file. +\gls{bib2gls} can then read these lines to find +out which entries have been used. (Remember that commands like +\cs{glsentryname} don't index, so any use of these commands won't +add a corresponding \cs{glsxtr@record} entry to the \texttt{.aux} +file.) See \sectionref{sec:bib2gls} for further details. + +\item[{\pkgoptdef{equations}}] (New to v1.37.) This option will +cause the default location counter to automatically switch +to \ctr{equation} when inside a numbered equation environment, such +as \env{equation} or \env{align}. The counter can be explicitly +overridden with \gloskey[glslink]{counter} in the optional +arguments of commands like \cs{glslink} or \cs{gls} as usual. + +\item[{\pkgoptdef{floats}}] (New to v1.37.) This option will +cause the default location counter to automatically switch +to the corresponding counter when inside a floating environment, +such as \env{figure} or \env{table}. The counter can be explicitly +overridden with \gloskey[glslink]{counter} in the optional +arguments of commands like \cs{glslink} or \cs{gls} as usual. +Remember that within floats it's the \cs{caption} command that actually uses +\cs{refstepcounter}, so indexing before the caption will result in +the wrong reference. The commands for use in captions and sections, +such as \cs{glsfmttext} and \cs{glsfmtshort}, don't index. (See +\sectionref{sec:headtitle}). You may +want to consider using \cs{glsadd} after the caption (not before). For example: +\begin{verbatim} +\begin{figure}[htbp] + \centering + \includegraphics{example-image} + \caption{Sample \glsfmttext{foobar} figure} + \glsadd{foobar} +\end{figure} +\end{verbatim} + +\item[{\pkgoptdef{indexcounter}}] (New to v1.29.) This option (which +doesn't take a value) is primarily intended for use with +\gls{bib2gls} (v1.4+) and \sty{hyperref}. It can be used with +\gls{makeindex} or \gls{xindy} but it will interfere with the +\gls{numberlist} collation, so you won't have ranges and you'll have +duplicate page numbers present (but each page number will link to +the relevant part of the page where the indexing occurred). This +option automatically implements \pkgopt[wrglossary]{counter}. + +\begin{important} +This option works by incrementing \ctr{wrglossary} and +adding \ics{label}. This can cause a problem if the indexing +occurs in an \env{equation} environment as \sty{amsmath} +forbids multiple occurrences of \cs{label} (resulting in the +\qt{Multiple \cs{label}'s} error). It's best to change the counter +to \ctr{page} or \ctr{equation} when in maths mode with this option. +For example: +\begin{verbatim} +\renewcommand{\glslinkpresetkeys}{% + \ifmmode \setkeys{glslink}{counter=equation}\fi} +\renewcommand{\glsaddpresetkeys}{% + \ifmmode \setkeys{glossadd}{counter=equation}\fi} +\end{verbatim} +\end{important} + +By default (with \sty{hyperref}), the page numbers in +\glspl{numberlist} link back to the top of the relevant page +(provided the format uses \cs{glshypernumber}). The +\pkgopt{indexcounter} option is designed to link back to the place +within the page where the indexing occurred. It does this by +creating a new counter (called \ctr{wrglossary}) that's incremented +with \cs{refstepcounter} every time an entry is indexed (but not via +cross-referencing commands, such as \cs{glssee}). A \cs{label} is +placed immediately after the increment command allowing the +back-referenced to be obtained with \cs{pageref}. The location, as +seen by the indexing application, is the value of the +\ctr{wrglossary} counter but this value is substituted with the page +reference when \gls{numberlist} is typeset. Since the counter is +used by all entries and is incremented every time any indexing +occurs, neither \gls{makeindex} nor \gls{xindy} can correctly +collate the lists. For example, if the first term to be referenced +is indexed three times on page~5 without any intervening terms then +the actual locations obtained from \ctr{wrglossary} will be 1, 2 and +3, which \gls{xindy} and \gls{makeindex} will try to form into the +range 1--3, but they should actually all simply appear as page~5, +whereas it can actually end up with 5--5. Conversely, a range may +not be formed where it would naturally occur if just the \ctr{page} +counter was used. + +Since \gls{bib2gls} is designed specifically to work with +\styfmt{glossaries-extra}, \gls{bib2gls} (v1.4+) will check for +\ctr{wrglossary} locations. If the default +\texttt{--merge-wrglossary-records} is on, then any records for the +same page for a given entry will be merged. In the above example +with three references on page~5, only a single record for page~5 for +that entry will be added to the \gls{numberlist} and it will link +back to the first instance on that page. Whereas if you use the +\texttt{--no-merge-wrglossary-records} switch, the \gls{numberlist} +will contain three instance of page~5, with each linking to the +corresponding place on that page. In both cases, consecutive pages +can form ranges, but it may look strange in the second case. + +See the \gls{bib2gls} documentation for the +\texttt{save-index-counter} resource option for more details. + +\item[{\pkgoptdef{docdef}}] This option governs the use of +\cs{newglossaryentry}. It was originally a boolean option, +but as from version 1.06, it can now take one of the following values (if +the value is omitted, \pkgoptfmt{true} is assumed): +\begin{itemize} +\item[{\pkgopt[false]{docdef}}] \ics{newglossaryentry} is not +permitted in the \env{document} environment (default). + +\item[{\pkgopt[true]{docdef}}] \cs{newglossaryentry} behaves as it +does in the base \styfmt{glossaries} package. That is, where +its use is permitted in the \env{document} environment, it +uses the \texttt{.glsdefs} temporary file to store the entry +definitions so that on the next \LaTeX\ run the entries are +defined at the beginning of the \env{document} environment. +This allows the entry information to be referenced in the glossary, +even if the glossary occurs before \cs{newglossaryentry}. +(For example, when the glossary is displayed in the front matter.) +This method of saving the definitions for the next \LaTeX\ run +has drawbacks that are detailed in the \styfmt{glossaries} user +manual. + +Remember that if \cs{newglossaryentry} wouldn't be allowed +in the \env{document} environment with the +base \styfmt{glossaries} package, then it still won't +be allowed with \pkgopt[true]{docdefs}. +If your glossaries occur at the end of the document, consider using +\pkgopt[restricted]{docdef} instead. + +\item[{\pkgopt[restricted]{docdef}}] (new to version 1.06) +\ics{newglossaryentry} is permitted in the \env{document} +environment without using the \texttt{.glsdefs} file. This means +that all entries must be defined before the glossary is displayed, +but it avoids the complications associated with saving the +entry details in a temporary file. You will still need to take +care about any changes made to characters that are required +by the \meta{key}=\meta{value} mechanism (that is, the comma and +equal sign) and any \gls{makeindex} or \gls{xindy} character that +occurs in the \gloskey{sort} key or label. If any of those +characters are made active in the document, then it can cause +problems with the entry definition. This option will allow +\cs{newglossaryentry} to be used in the document with +\cs{makenoidxglossaries}, but note that \cs{longnewglossaryentry} +remains a preamble-only command. + +With this option, if an entry appears in the glossary before +it has been defined, an error will occur (or a warning if +the \pkgopt[warn]{undefaction} option is used.) If you edit your +document and either remove an entry or change its label, you may +need to delete the document's temporary files (such as the +\texttt{.aux} and \texttt{.gls} files). + +\item[{\pkgopt[atom]{docdef}}] (new to version 1.34) +This option behaves like \pkgopt[restricted]{docdef} but creates the +\texttt{.glsdefs} file for +\href{https://atom.io/packages/autocomplete-glossaries}{atom's +autocomplete support}. This file isn't input by +\styfmt{glossaries-extra} and so associated problems with the use of +this file are avoided, but it allows the autocomplete support to +find the labels in the file. As with \pkgopt[restricted]{docdef}, +entries may be defined in the preamble or anywhere in the document, +but they may only be referenced after they have been defined. +Entries must be defined before the associated glossary is displayed. + +\end{itemize} + +The \styfmt{glossaries} package allows +\cs{newglossaryentry} within the \env{document} environment (when +used with \gls{makeindex} or \gls{xindy}) but the user manual warns +against this usage. By default the \styfmt{glossaries-extra} package +\emph{prohibits} this, only allowing definitions within the +preamble. If you are really determined to define entries in the +\env{document} environment, despite all the associated drawbacks, +you can restore this with \pkgopt[true]{docdef}. Note that this +doesn't change the prohibitions that the \styfmt{glossaries} +package has in certain circumstances (for example, when using +\qt{option~1}). See the \styfmt{glossaries} user manual for further +details. A better option if document definitions are required +is \pkgopt[restricted]{docdef}. Only use \pkgopt[true]{docdef} +if document definitions are necessary and one or more of the +glossaries occurs in the front matter. + +\begin{sloppypar} +This option affects commands that internally use +\cs{newglossaryentry}, such as \cs{newabbreviation}, but not +the \qt{on-the-fly} commands described in \sectionref{sec:onthefly}. +\end{sloppypar} + +\item[{\pkgoptdef{nomissingglstext}}] This is a boolean option. +If true, this will suppress the warning written to the transcript +and the warning text that will appear in the +document if the external glossary files haven't been generated due +to an incomplete document build. However, it's probably simpler +just to fix whatever has caused the failure to build the external +file or files. + +\item[{\pkgoptdef{abbreviations}}] This option has no value and can't +be cancelled. If used, +it will automatically create a new glossary with the label +\texttt{abbreviations} and redefines \cs{glsxtrabbrvtype} to this +label. In addition, it defines a shortcut command +\begin{definition}[\DescribeMacro\printabbreviations] +\cs{printabbreviations}\oarg{options} +\end{definition} +which is equivalent to +\begin{alltt} +\cs{printglossary}[type=\cs{glsxtrabbrvtype},\meta{options}] +\end{alltt} +If \sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtabbreviations] +\cs{printunsrtabbreviations}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + +The title of the new glossary is given by +\begin{definition}[\DescribeMacro\abbreviationsname] +\cs{abbreviationsname} +\end{definition} +If this command is already defined, it's left unchanged. Otherwise +it's defined to \qt{Abbreviations} if \sty{babel} hasn't been loaded +or \cs{acronymname} if \sty{babel} has been loaded. However, if +you're using \sty{babel} it's likely you will need to change this. +(See \sectionref{sec:lang} for further details.) + +\begin{important} +If you don't use the \pkgopt{abbreviations} package option, +the \cs{abbreviationsname} command won't be defined (unless it's +defined by an included language file). +\end{important} + +If the \pkgopt{abbreviations} option is used and the +\pkgopt{acronym} option provided by the \styfmt{glossaries} +package hasn't been used, then \ics{acronymtype} +will be set to \ics{glsxtrabbrvtype} so that acronyms defined with +\ics{newacronym} can be added to the list of abbreviations. If you +want acronyms in the \texttt{main} glossary and other abbreviations in the +\texttt{abbreviations} glossary then you will need to redefine +\cs{acronymtype} to \texttt{main}: +\begin{verbatim} +\renewcommand*{\acronymtype}{main} +\end{verbatim} + +Note that there are no analogous options to the \styfmt{glossaries} +package's \pkgopt{acronymlists} option (or associated commands) +as the abbreviation mechanism is handled differently with +\styfmt{glossaries-extra}. + +\item[{\pkgoptdef{symbols}}] This is passed to \styfmt{glossaries} but +will additionally define +\begin{definition}[\DescribeMacro\glsxtrnewsymbol] +\cs{glsxtrnewsymbol}\oarg{options}\marg{label}\marg{symbol} +\end{definition} +which is equivalent to +\begin{alltt} +\cs{newglossaryentry}\marg{label}\{name=\marg{symbol}, + sort=\marg{label},type=symbols,category=symbol,\meta{options}\} +\end{alltt} +Note that the \gloskey{sort} key is set to the \meta{label} +not the \meta{symbol} as the symbol will likely contain commands. + +If \sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtsymbols] +\cs{printunsrtsymbols}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + +\item[{\pkgoptdef{numbers}}] This is passed to \styfmt{glossaries} but +will additionally define +\begin{definition}[\DescribeMacro\glsxtrnewnumber] +\cs{glsxtrnewnumber}\oarg{options}\marg{number} +\end{definition} +which is equivalent to +\begin{alltt} +\cs{newglossaryentry}\marg{label}\{name=\marg{number}, + sort=\marg{label},type=numbers,category=number,\meta{options}\} +\end{alltt} + +If \sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtnumbers] +\cs{printunsrtnumbers}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + +\item[{\pkgoptdef{acronyms} (or \pkgoptdef{acronym})}] This is +passed to \styfmt{glossaries} but if +\sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtacronyms] +\cs{printunsrtacronyms}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + +\begin{important} +This option defines a new glossary with the label \texttt{acronym} +not \texttt{acronyms}. You may find it easier to reference it +with the command \ics{acronymtype}. +\end{important} + +\item[{\pkgoptdef{index}}] This is +passed to \styfmt{glossaries} but if +\sty{glossaries-extra-bib2gls} is also loaded then this option +will additionally provide: +\begin{definition}[\DescribeMacro\printunsrtindex] +\cs{printunsrtindex}\oarg{options} +\end{definition} +which uses \ics{printunsrtglossary}. + +\item[{\pkgoptdef{shortcuts}}] Unlike the \styfmt{glossaries} package +option of the same name, this option isn't boolean but has multiple +values: +\begin{itemize} +\item \pkgopt[acronyms]{shortcuts} (or \pkgopt[acro]{shortcuts}): +set the shortcuts provided by the \styfmt{glossaries} package for +acronyms (such as \cs{ac}). Note that the short and long forms don't +use \cs{glsxtrshort} and \cs{glsxtrlong} but use the original +\cs{acrshort} and \cs{acrlong}, which don't recognise multiple +abbreviation styles. The better option with \styfmt{glossaries-extra} +is \pkgopt[ac]{shortcuts}. + +\item \pkgopt[ac]{shortcuts}: +set the shortcuts provided by the \styfmt{glossaries} package for +acronyms (such as \cs{ac}) but uses the \styfmt{glossaries-extra} +interface (such as \cs{glsxtrshort} rather than \cs{acrshort}). +In this case \cs{ac} is defined as \cs{cgls} rather than +\cs{gls}. + +\item \pkgopt[abbreviations]{shortcuts} (or +\pkgopt[abbr]{shortcuts}): +set the abbreviation shortcuts provided by \styfmt{glossaries-extra}. (See +\sectionref{sec:abbrshortcuts}.) These settings don't switch on the +acronym shortcuts provided by the \styfmt{glossaries} package. + +\item \pkgopt[other]{shortcuts}: set the \qt{other} +shortcut commands, but not the shortcut commands for abbreviations +or the acronym shortcuts provided by \styfmt{glossaries}. +The \qt{other} shortcuts are: +\begin{itemize} +\item \ics{newentry} equivalent to \ics{newglossaryentry} +\item \ics{newsym} equivalent to \ics{glsxtrnewsymbol} (see the +\pkgopt{symbols} option). +\item \ics{newnum} equivalent to \ics{glsxtrnewnumber} (see the +\pkgopt{numbers} option). +\end{itemize} + +\item \pkgopt[all]{shortcuts} (or \pkgopt[true]{shortcuts}): +implements \pkgopt[ac]{shortcuts}, \pkgopt[abbreviations]{shortcuts} +and \pkgopt[other]{shortcuts}. + +\item \pkgopt[none]{shortcuts} (or \pkgopt[false]{shortcuts}): +don't define any of the shortcut commands (default). +\end{itemize} + +Note that multiple invocations of the \pkgopt{shortcuts} option +\emph{within the same option list} will override each other. +\end{description} + +After the \styfmt{glossaries-extra} package has been loaded, you can +set available options using +\begin{definition}[\DescribeMacro\glossariesextrasetup] +\cs{glossariesextrasetup}\marg{options} +\end{definition} +The \pkgopt{abbreviations} and \pkgopt{docdef} options may only be +used in the preamble. Additionally, \pkgopt{docdef} can't be used +after \ics{makenoidxglossaries}. + +\chapter{Modifications to Existing Commands and Styles} +\label{sec:modifications} + +The \styfmt{glossaries} package provides \ics{nopostdesc} +which may be used in the \gloskey{description} to suppress +the post-description hook. The \styfmt{glossaries-extra} package +provides another command +\begin{definition}[\DescribeMacro\glsxtrnopostpunc] +\cs{glsxtrnopostpunc} +\end{definition} +which has a similar function but only suppresses the +post-description punctuation. It doesn't suppress the use of +\cs{glsxtrpostdescription} which allows the use of +category-dependent post-description hooks. (Note that the +punctuation, which is in the original base hook \cs{glspostdescription}, +comes after the extended post-description hook +\cs{glsxtrpostdescription} not before.) The post-description hook +can counter-act the effect of \cs{glsxtrnopostpunc} using +\begin{definition}[\DescribeMacro\glsxtrrestorepostpunc] +\cs{glsxtrrestorepostpunc} +\end{definition} +These commands have no effect outside of the glossary (except with +standalone entries that use \cs{glsxtractivatenopost} and +\cs{glspostdescription}, see \sectionref{sec:glossentry}). + +The \styfmt{glossaries} package provides +\begin{definition}[\DescribeMacro\glsseeitemformat] +\cs{glsseeitemformat}\marg{label} +\end{definition} +to format items in a cross-reference list (identified with the +\gloskey{see} key or \cs{glssee}). This was originally defined to +use \cs{glsentryname}\marg{label} since it makes more sense for the +cross-reference to match the way the term appears in the glossary. +Unfortunately this caused a problem when the \gloskey{name} field +was sanitized, which used to be the default setting, so +\styfmt{glossaries} v3.0 changed the default definition of this +command to use \cs{glsentrytext} instead. Since the \gloskey{name} +and \gloskey{text} field are quite often the same, this change +usually doesn't have a noticeable effect. However, now that the +\gloskey{name} field is no longer sanitized (following the redesign +of \styfmt{glossaries} v4.0) it makes more sense to restore this +command to its original behaviour, but to take account of +abbreviations \styfmt{glossaries-extra} redefines this as: +\begin{verbatim} +\renewcommand*{\glsseeitemformat}[1]{% + \ifglshasshort{\glslabel}{\glsaccesstext{#1}}{\glsaccessname{#1}}% +} +\end{verbatim} +If you want to restore the \styfmt{glossaries} v3.0+ definition just do: +\begin{verbatim} +\renewcommand*{\glsseeitemformat}[1]{\glsentrytext{#1}} +\end{verbatim} +The \sty{glossaries-extra} package provides \ics{glsxtrhiername} +and its case-changing variants that may be used within +the definition of \cs{glsseeitemformat} if required. These +display the hierarchy for sub-entries rather than just the name, +which may be more helpful in cross-references. See +\sectionref{sec:see} for further details. + +The commands used by \styfmt{glossaries} to automatically produce an +error if an entry is undefined (such as \ics{glsdoifexists}) are +changed to take the \pkgopt{undefaction} option into account. + +The \ics{newignoredglossary}\marg{type} command now (as from v1.11) has a starred +version that doesn't automatically switch off the hyperlinks. +This starred version may be used with the \catattr{targeturl} +attribute to create a link to an external URL. (See +\sectionref{sec:categories} for further details.) +As from v1.12 both the starred and unstarred version check +that the glossary doesn't already exist. (The \styfmt{glossaries} +package omits this check.) + +You can now provide an ignored glossary with: +\begin{definition}[\DescribeMacro\provideignoredglossary] +\cs{provideignoredglossary}\marg{type} +\end{definition} +which will only define the glossary if it doesn't already exist. +This also has a starred version that doesn't automatically switch +off hyperlinks. + +The individual glossary displaying commands \ics{printglossary}, +\ics{printnoidxglossary} and \cs{printunsrtglossary} have two extra +keys: + +\begin{itemize} +\item \gloskey[printglossary]{target}. This is a boolean key which can +be used to switch off the automatic hypertarget for each entry. +Unlike \cs{glsdisablehyper} this doesn't switch off hyperlinks, so +any cross-references within the glossary won't be affected. This is +a way of avoiding duplicate target warnings if a glossary needs to +be displayed multiple times. +\item +\gloskey[printglossary]{targetnameprefix}\texttt{=}\marg{prefix}. Another way +of avoiding duplicate target names is to set a prefix +used for the names. Unlike changing \cs{glolinkprefix} this doesn't affect +any hyperlinks (such as those created with \cs{gls}). +\item +\gloskey[printglossary]{prefix}\texttt{=}\marg{prefix}. If you do +actually want to locally change \cs{glolinkprefix}, you can use +the \gloskey{prefix} key instead. You need to use the matching +\gloskey[glslink]{prefix} key in commands like \cs{gls}. + +\item +\gloskey[printglossary]{label}\texttt{=}\marg{label}. Labels +the glossary with \texttt{\cs{label}\marg{label}} and also +defines \cs{@currentlabelname} to the glossary's TOC title +(to provide text for \cs{nameref}). You can also set the +label before the glossary using: +\begin{definition}[\DescribeMacro\glsxtrsetglossarylabel] +\cs{glsxtrsetglossarylabel}\marg{label} +\end{definition} +but take care of duplicate labels if it's not scoped. +\end{itemize} + +The \cs{newglossaryentry} command has three new keys: +\begin{itemize} +\item \gloskey{category}, which sets the category label for the given +entry. By default this is \texttt{general}. See +\sectionref{sec:categories} for further information about +categories. +\item \gloskey{alias}, which allows an entry to be alias to another +entry. See \sectionref{sec:alias} for further details. +\item \gloskey{seealso}, which performs much like \gloskey{see}, but +allows for separate \qt{see} and \qt{see also} treatment. +See \sectionref{sec:see} for further details. +\end{itemize} +The test file \texttt{example-glossaries-xr.tex} contains +dummy entries with a mixture of \gloskey{see}, \gloskey{alias} +and \gloskey{seealso} keys for use with minimal working examples. +There are also \texttt{example-glossaries-*.bib} files that +correspond to each \texttt{example-glossaries-*.tex} file +for testing \gls{bib2gls}. + +The \cs{longnewglossaryentry} command now has a starred version +(as from v1.12) that doesn't automatically insert +\begin{verbatim} +\leavevmode\unskip\nopostdesc +\end{verbatim} +at the end of the description field. +\begin{definition}[\DescribeMacro\longnewglossaryentry] +\cs{longnewglossaryentry}*\marg{label}\marg{options}\marg{description} +\end{definition} +The \gloskey{descriptionplural} key is left unset unless explicitly +set in \meta{options}. + +The unstarred version no longer hard-codes the above code (which +removes trailing space and suppresses the post-description hook) but instead +uses: +\begin{definition}[\DescribeMacro\glsxtrpostlongdescription] +\cs{glsxtrpostlongdescription} +\end{definition} +This can be redefined to allow the post-description hook to work +but retain the \cs{unskip} part if required. +For example: +\begin{verbatim} +\renewcommand*{\glsxtrpostlongdescription}{\leavevmode\unskip} +\end{verbatim} +This will discarded unwanted trailing space at the end of the description +but won't suppress the post-description hook. + +The unstarred version also alters the base \sty{glossaries} package's +treatment of the \gloskey{descriptionplural} key. Since a +plural description doesn't make much sense for multi-paragraph +descriptions, the default behaviour with +\sty{glossaries-extra}'s +\cs{longnewglossaryentry} is to simply leave the plural description +unset unless explicitly set using the \gloskey{descriptionplural} +key. The \styfmt{glossaries.sty} version of this command sets the description's +plural form to the same as the singular.\footnote{The +\gloskey{descriptionplural} key is a +throwback to the base package's original acronym mechanism before the introduction of +the \gloskey{long} and \gloskey{short} keys, where the long form was +stored in the \gloskey{description} field and the short form was stored in the +\gloskey{symbol} field.} + +Note that this modified unstarred version doesn't append +\cs{glsxtrpostlongdescription} to the description's plural form. + +The \ics{newterm} command (defined through the \pkgopt{index} package +option) is modified so that the category defaults to \category{index}. +The \ics{newacronym} command is modified to use the new abbreviation +interface provided by \styfmt{glossaries-extra}. +(See \sectionref{sec:abbreviations}.) + +The \cs{makeglossaries} command now has an optional argument. +\begin{definition}[\DescribeMacro\makeglossaries] +\cs{makeglossaries}\oarg{list} +\end{definition} +If \meta{list} is empty, \cs{makeglossaries} behaves as per +its original definition in the \styfmt{glossaries} package, +otherwise \meta{list} can be a comma-separated list of glossaries +that need processing with an external indexing application. + +This command is not permitted with the \pkgopt[only]{record} +package option. Without the optional argument, it's permitted +with \pkgopt[alsoindex]{record}. With the optional argument, +it's only permitted with the default \pkgopt[off]{record}. + +It should then be possible to use \cs{printglossary} for those +glossaries listed in \meta{list} and \cs{printnoidxglossary} +for the other glossaries. (See the accompanying file +\texttt{sample-mixedsort.tex} for an example.) + +\begin{important} +If you use the optional argument \meta{list}, you can't define +entries in the document (even with the \pkgopt{docdef} option). +\end{important} + +You will need at least version 2.20 of \gls{makeglossaries} or at +least version 1.3 of the Lua alternative \gls{makeglossaries-lite.lua} (both distributed +with \styfmt{glossaries} v4.27) to allow for this use of +\cs{makeglossaries}\oarg{list}. Alternatively, use the +\pkgopt{automake} option. + +\section{Entry Indexing} +\label{sec:wrglossary} + +As from version 1.31, there is a new command like \cs{glsadd} +where the mandatory argument is a comma-separated list +of labels: +\begin{definition}[\DescribeMacro\glsaddeach] +\cs{glsaddeach}\oarg{options}\marg{list} +\end{definition} +This simply iterates over \meta{list} and does +\cs{glsadd}\oarg{options}\marg{label} for each entry in the list. + +As from version 1.37, you can make commands like \cs{gls} or +\cs{glslink} automatically use \cs{glsadd} with specific options +when a given format is used (identified with +\texttt{format=\marg{format}} in the optional argument of the +corresponding \cs{gls}, \cs{glslink} etc). +\begin{definition}[\DescribeMacro\GlsXtrAutoAddOnFormat] +\cs{GlsXtrAutoAddOnFormat}\oarg{label}\marg{format list}\marg{glsadd options} +\end{definition} +The optional argument \meta{label} defaults to \cs{glslabel} and +indicates the label to use in \cs{glsadd} and so needs to be +expandable. The \meta{format list} is a comma-separated list +of format values that will trigger the automated adding. The +\meta{glsadd options} are the options to pass to \cs{glsadd} with +\texttt{format=\marg{format}} prepended to the list. + +For example, with: +\begin{verbatim} +\GlsXtrAutoAddOnFormat{hyperbf}{counter=chapter} +\end{verbatim} +then \verb|\gls[format=hyperbf]{sample}| will be equivalent to +\begin{verbatim} +\glsadd[format=hyperbf,counter=chapter]{sample}\gls[format=hyperbf]{sample} +\end{verbatim} +Note that the explicit range markers will prevent a match +unless you include them in \meta{format list} (in which case, be +sure to add both the start and end formats). + +Here's another example: +\begin{verbatim} +\GlsXtrAutoAddOnFormat[dual.\glslabel]{hyperbf}{} +\end{verbatim} +In this case \verb|\gls[format=hyperbf]{sample}| will now be +equivalent to: +\begin{verbatim} +\glsadd[format=hyperbf]{dual.sample}\gls[format=hyperbf]{sample} +\end{verbatim} + +\begin{important} +\cs{GlsXtrAutoAddOnFormat} is not applied to \cs{glsadd} +as it could cause an infinite loop. +\end{important} +The \styfmt{glossaries-extra} package provides extra keys for +commands like \cs{gls} and \cs{glstext}: +\begin{description} +\item[{\gloskey[glslink]{noindex}}] This is a boolean key. If true, +this suppresses the indexing. (That is, it prevents \cs{gls} or +whatever from adding a line to the external glossary file.) +This is more useful than the \pkgopt{indexonlyfirst} package option +provided by \styfmt{glossaries}, as the \gls{firstuse} might not be the most +pertinent use. (If you want to apply \pkgopt{indexonlyfirst} +to selected entries, rather than all of them, you can use +the \catattr{indexonlyfirst} attribute, see +\sectionref{sec:categories} for further details.) +Note that the \gloskey[glslink]{noindex} key isn't available +for \ics{glsadd} (and \ics{glsaddall}) since the whole purpose +of that command is to index an entry. + +\item[{\gloskey[glslink]{wrgloss}}] (New to v1.14.) +This is may only take the +values \optfmt{before} or \optfmt{after}. By default, commands +that both index and display link text (such as \cs{gls}, +\cs{glstext} and \cs{glslink}), perform the indexing before +the link text as the indexing creates a whatsit that can cause +problems if it occurs after the link text. However, it may +be that in some cases (such as long phrases) you may actually +want the indexing performed after the link text. In this +case you can use \texttt{wrgloss=after} for specific +instances. Note that this option doesn't +have an effect if the indexing has been suppressed through +other settings (such as \gloskey[glslink]{noindex}). + +The default value is set up using +\begin{definition}[\DescribeMacro\glsxtrinitwrgloss] +\cs{glsxtrinitwrgloss} +\end{definition} +which is defined as: +\begin{verbatim} +\newcommand*{\glsxtrinitwrgloss}{% + \glsifattribute{\glslabel}{wrgloss}{after}% + {% + \glsxtrinitwrglossbeforefalse + }% + {% + \glsxtrinitwrglossbeforetrue + }% +} +\end{verbatim} +This sets the conditional +\begin{definition}[\DescribeMacro\ifglsxtrinitwrglossbefore] +\cs{ifglsxtrinitwrgloss} +\end{definition} +which is used to determine where to perform the indexing. + +This means you can set the \catattr{wrgloss} +attribute to \optfmt{after} to automatically use this as +the default for entries with that category attribute. (Note that +adding \gloskey[glslink]{wrgloss} to the default options +in \ics{GlsXtrSetDefaultGlsOpts} will override +\cs{glsxtrinitwrgloss}.) + +\item[{\gloskey[glslink]{hyperoutside}}] (New to v1.21.) This is a +boolean key. The default is \texttt{hyperoutside=true}, which puts +the hyperlink outside \cs{glstextformat}, so that commands like +\cs{gls} will effectively do +\begin{alltt} +\cs{hyperlink}\marg{target}\{\cs{glstextformat}\marg{link text}\} +\end{alltt} +This is the same behaviour as with the base \styfmt{glossaries} +package. With \texttt{hyperoutside=false}, \cs{hyperlink} is placed +inside the argument of \cs{glstextformat}: +\begin{alltt} +\cs{glstextformat}\{\cs{hyperlink}\marg{target}\marg{link text}\} +\end{alltt} +You can use the \catattr{hyperoutside} category attribute to set +the default for a given category. This can be combined +with the use of the \catattr{textformat} attribute to counteract +any interference caused by \cs{hyperlink}. +For example: +\begin{verbatim} +\glssetcategoryattribute{mathrelation}{hyperoutside}{false} +\end{verbatim} +will set \texttt{hyperoutside=false} for all entries that are +assigned to the category \texttt{mathrelation} and +\begin{verbatim} +\glssetcategoryattribute{mathrelation}{textformat}{mathrel} +\end{verbatim} +will use \cs{mathrel} instead of \cs{glstextformat} resulting in: +\begin{alltt} +\cs{mathrel}\{\cs{hyperlink}\marg{target}\marg{link text}\} +\end{alltt} +for entries with the \gloskey{category} key set to +\texttt{mathrelation}. + +\item[{\gloskey[glslink]{textformat}}] This key must have a +control sequence name as its value. The command formed from +this name must exist and must take one argument. (Use +\texttt{relax} for default behaviour.) If set, this overrides +the \catattr{textformat} attribute and \cs{glstextformat}. +See the \sty{soul} example in \sectionref{sec:glsunset}. + +\item[{\gloskey[glslink]{prefix}}] Locally redefines +\ics{glolinkprefix} to the given value. It should match the prefix +for the desired glossary. + +\item[{\gloskey[glslink]{thevalue}}] Explicitly set the location to +this value (see below). + +\item[{\gloskey[glslink]{theHvalue}}] Set the corresponding +hyperlink location (see below). + +\end{description} + +There is a new hook that's used each time indexing information is +written to the external glossary files: +\begin{definition}[\DescribeMacro\glsxtrdowrglossaryhook] +\cs{glsxtrdowrglossaryhook}\marg{label} +\end{definition} +where \meta{label} is the entry's label. This does nothing by +default but may be redefined. (See, for example, the +accompanying sample file \texttt{sample-indexhook.tex}, +which uses this hook to determine which entries haven't been +indexed.) + +There's also a new hook (from v1.26) that's used immediately +before the options are set by the \cs{gls}-like and +\cs{glstext}-like commands: +\begin{definition}[\DescribeMacro\glslinkpresetkeys] +\cs{glslinkpresetkeys} +\end{definition} +(The base package provides \ics{glslinkpostsetkeys} that's +used immediately after the options are set.) + +As from version 1.30 there are also similar hooks for \cs{glsadd}: +\begin{definition}[\DescribeMacro\glsaddpresetkeys] +\cs{glsaddpresetkeys} +\end{definition} +and +\begin{definition}[\DescribeMacro\glsaddpostsetkeys] +\cs{glsaddpostsetkeys} +\end{definition} +For example, to default to using the \ctr{equation} counter in maths +mode: +\begin{verbatim} +\renewcommand{\glslinkpresetkeys}{% + \ifmmode \setkeys{glslink}{counter=equation}\fi} +\renewcommand{\glsaddpresetkeys}{% + \ifmmode \setkeys{glossadd}{counter=equation}\fi} +\end{verbatim} +In this case, the counter can be overridden with an explicit use of +\gloskey{counter} in the optional argument of \cs{gls} or +\cs{glsadd}. (As from version 1.37, a simpler method is to just use +the \pkgopt{equations} package option.) + +Alternatively, to enforce this (overriding the option +argument): +\begin{verbatim} +\renewcommand{\glslinkpostsetkeys}{% + \ifmmode \setkeys{glslink}{counter=equation}\fi} +\renewcommand{\glsaddpostsetkeys}{% + \ifmmode \setkeys{glossadd}{counter=equation}\fi} +\end{verbatim} + +As from version 1.14, there are two new keys for \cs{glsadd}: +\gloskey[glsadd]{thevalue} and \gloskey[glsadd]{theHvalue}. +These keys are designed for manually adding explicit locations +rather than obtaining the value from the associated counter. +As from version 1.19, these two keys are also available for commands +like \cs{gls} and \cs{glslink}. The \gloskey[glsadd]{thevalue} keys is +intended primarily for adding locations in supplementary material +that can't be obtained from a counter. + +The principle key \gloskey[glslink]{thevalue} is for the location value. The +other key \gloskey[glslink]{theHvalue} can be used to +extract a prefix value for the first argument of commands like +\ics{glsnoidxdisplayloc}. Its value must be in the format +\meta{prefix}\meta{location}. In general, there's little need for +this key as the prefix is typically associated with a counter that can be +used to form hypertargets. + +\begin{important} +If you use \gloskey[glsadd]{thevalue}, you must make sure that you +use an indexing application that will accept the given value. +\end{important} + +For example, \app{makeindex} will only accept locations in the form +[\meta{num}\meta{sep}]*\meta{num} where \meta{num} is an arabic +number (0, 1, \ldots), roman numeral (i, ii, \ldots\ or I, II, +\ldots) or a character from a, \ldots, z or A, \ldots, Z, and +[\meta{num}\meta{sep}]* indicates zero or more instances of a number +followed by the recognised separator character (set with +\cs{glsSetCompositor}). This means that \app{makeindex} won't +accept, for example, +\begin{verbatim} +\glsadd[thevalue={Supplementary Material}]{sample} +\end{verbatim} +This location value will be accepted by \gls{bib2gls}, since it will +allow any location and will only try forming ranges if the location +matches any of its numerical patterns. +In the case of \app{xindy}, you'll need to add a rule that can match +the value. If you're using \sty{hyperref}, you may need to use the +\gloskey[glslink]{format} key to prevent a hyperlink if one can't +naturally be formed from the prefix, counter and location value. + +For example, suppose the file \texttt{suppl.tex} contains: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries-extra} + +\newglossaryentry{sample}{name={sample},description={an example}} + +\renewcommand{\thepage}{S.\arabic{page}} + +\begin{document} +First page. +\newpage +\gls{sample}. +\end{document} +\end{verbatim} +This has an entry on page S.2. Suppose another document wants to +include this location in the glossary. Then this can be done by +setting \gloskey[glsadd]{thevalue} to \texttt{S.2}. For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries-extra} + +\makeglossaries + +\newglossaryentry{sample}{name={sample},description={an example}} + +\begin{document} +Some \gls{sample} text. + +\printglossaries +\glsadd[thevalue={S.2}]{sample} +\end{document} +\end{verbatim} +This location value will be accepted by \app{makeindex} as it's in +the form \meta{num}\meta{sep}\meta{num}. + +If you want hyperlinks, things are more complicated. First +you need to set the \catattr{externallocation} attribute to the location of +the PDF file. For example: +\begin{verbatim} +\glssetcategoryattribute{supplemental}{externallocation}{suppl.pdf} + +\newglossaryentry{sample}{category=supplemental, + name={sample},description={an example}} +\end{verbatim} +Next you need to add \texttt{glsxtrsupphypernumber} as the format: +\begin{verbatim} +\glsadd[thevalue={S.2},format=glsxtrsupphypernumber]{sample} +\end{verbatim} +Both documents will need to use the \sty{hyperref} package. +Remember that the counter used for the location also needs to match. +If \cs{theH}\meta{counter} is defined in the other document +and doesn't match in the referencing document, then you need +to use \gloskey[glsadd]{theHvalue} to set the appropriate value. +See the accompanying sample files \texttt{sample-suppl-hyp.tex} +and \texttt{sample-suppl-main-hyp.tex} for an example that uses +\sty{hyperref}. + +\begin{important} +The hyperlink for the supplementary location may or \emph{may not} +take you to the relevant place in the external PDF file +\emph{depending on your PDF viewer}. Some may not support external +links, and some may take you to the first page or last visited page. +\end{important} + +For example, if both \texttt{sample-suppl-hyp.pdf} +and \texttt{sample-suppl-main-hyp.pdf} are in the same directory, +then viewing \texttt{sample-suppl-main-hyp.pdf} in Evince will +take you to the correct location in the linked document (when you +click on the S.2 external link), but Okular will take you to the top +of the first page of the linked document. + +This method can only be used where there is one external source +for the designated category (identified by the +\catattr{externallocation} attribute). For multiple sources, you need to use +\gls{bib2gls} version 1.7+, which is the better method in general as it can +automatically fetch the relevant locations from the \texttt{.aux} +files of the designated external documents without the need to +explicitly use \cs{glsadd}. + +\section{Cross-References (\qt{see} and \qt{see also})} +\label{sec:see} + +The value of the \gloskey{see} key is now saved +as a field. This isn't the case with \styfmt{glossaries}, where +the \gloskey{see} value is simply used to directly +write a line to the corresponding glossary file and is then +discarded. This is why the \gloskey{see} key can't be +used before \ics{makeglossaries} (since the file hasn't been opened +yet). It's also the reason why the \gloskey{see} key doesn't have +any effect when used in entries that are defined in the +\env{document} environment. Since the value isn't saved, +it's not available when the \texttt{.glsdefs} file is created at the +end of the document and so isn't available at the start of the +\env{document} environment on the next run. + +This modification allows \styfmt{glossaries-extra} to provide +\begin{definition}[\DescribeMacro\glsxtraddallcrossrefs] +\cs{glsxtraddallcrossrefs} +\end{definition} +which is used at the end of the document to automatically add +any unused cross-references unless the package option +\pkgopt{indexcrossrefs} was set to false. + +As a by-product of this enhancement, the \gloskey{see} key will now +work for entries defined in the \env{document} environment, but it's still +best to define entries in the preamble, and the \gloskey{see} key +still can't perform any indexing before the file has been opened by +\cs{makeglossaries}. Note that \styfmt{glossaries} v4.24 introduced +the \pkgopt{seenoindex} package option, which can be used to +suppress the error when the \gloskey{see} key is used before +\cs{makeglossaries}, so \pkgopt[ignore]{seenoindex} will allow the +\gloskey{see} value to be stored even though it may not be possible +to index it at that point. + +As from version 1.06, you can display the cross-referenced +information for a given entry using +\begin{definition}[\DescribeMacro\glsxtrusesee] +\cs{glsxtrusesee}\marg{label} +\end{definition} +This internally uses +\begin{definition}[\DescribeMacro\glsxtruseseeformat] +\cs{glsxtruseseeformat}\marg{tag}\marg{xr list} +\end{definition} +where \meta{tag} and \meta{xr list} are obtained from the value of +the entry's \gloskey{see} field (if non-empty). +By default, this just does \cs{glsseeformat}\oarg{tag}\marg{xr +list}\verb|{}|, which is how the cross-reference is displayed in the +\gls{numberlist}. Note that \cs{glsxtrusesee} does nothing if the +\gloskey{see} field hasn't been set for the entry given by +\meta{label}. + +As with the base \sty{glossaries} package, \cs{glsseeformat} +is defined to do \texttt{\cs{emph}\marg{tag} \cs{glsseelist}\marg{xr +list}}. The third argument is always ignored and is present for +\app{makeindex}, which always requires a final argument to +encapsulate the associated location. The command +\begin{definition} +\ics{glsseelist}\marg{xr list} +\end{definition} +used to iterate over the list of cross-reference labels is also +unchanged from the base \sty{glossaries} package, with each item in +the list formatted according to: +\begin{definition} +\ics{glsseeitem}\marg{label} +\end{definition} +This is defined by the \sty{glossaries} package to: +\begin{alltt} +\cs{glshyperlink}[\cs{glsseeitemformat}\marg{label}]\marg{label} +\end{alltt} +So the actual formatting for each cross-referenced entry is +performed by \ics{glsseeitemformat}, which is redefined by +\sty{glossaries-extra}, as described in +\sectionref{sec:modifications}. This now displays the value +of the \gloskey{text} field for abbreviations and the value +of the \gloskey{name} field otherwise. There's no indication +of the entry hierarchy, which could confuse the reader. Therefore, +as from \sty{glossaries-extra} v1.37, there are some new commands +that include the hierarchical information. You may prefer to +redefine \cs{glsseeitemformat} to use one of this if you have +sub-entries. For example: +\begin{verbatim} +\renewcommand*{\glsseeitemformat}[1]{\glsxtrhiername{#1}} +\end{verbatim} + +The command: +\begin{definition}[\DescribeMacro\glsxtrhiername] +\cs{glsxtrhiername}\marg{label} +\end{definition} +performs a recursive action: +\begin{enumerate} +\item If the entry given by \meta{label} has a parent, then +\cs{glsxtrhiername}\marg{parent label} is done followed by +\cs{glsxtrhiernamesep} then: +\item If the entry given by \meta{label} is an abbreviation +(that is, it has the \gloskey{short} field set) then +the short form is displayed (using \cs{glsaccessshort}) +otherwise the name is displayed (using \cs{glsaccessname}). +\end{enumerate} +The first step above is skipped if the entry doesn't have a parent. +Each level is separated by: +\begin{definition}[\DescribeMacro\glsxtrhiernamesep] +\cs{glsxtrhiernamesep} +\end{definition} +which defaults to \qt{\glsxtrhiernamesep}. This can be redefined as +appropriate. + +There are some case-changing variants: +\begin{definition}[\DescribeMacro\Glsxtrhiername] +\cs{Glsxtrhiername}\marg{label} +\end{definition} +The top-level has the first letter changed to upper case +(either \cs{Glsaccessshort} or \cs{Glsaccessname}). There's +no case-change for sub-entries. + +\begin{definition}[\DescribeMacro\GlsXtrhiername] +\cs{GlsXtrhiername}\marg{label} +\end{definition} +All levels have the first letter changed to upper case +(either \cs{Glsaccessshort} or \cs{Glsaccessname}). + +\begin{definition}[\DescribeMacro\GLSxtrhiername] +\cs{GLSxtrhiername}\marg{label} +\end{definition} +The top-level is converted to upper case +(either \cs{GLSaccessshort} or \cs{GLSaccessname}). There's +no case-change for sub-entries. + +\begin{definition}[\DescribeMacro\GLSXTRhiername] +\cs{GLSXTRhiername}\marg{label} +\end{definition} +All levels are converted to upper case +(either \cs{GLSaccessshort} or \cs{GLSaccessname}). + +Suppose you want to suppress the \gls*{numberlist} +using \pkgopt{nonumberlist}. This will automatically prevent the +cross-references from being displayed. The +\pkgopt{seeautonumberlist} package option will automatically +enable the \gls*{numberlist} for entries that have the \gloskey{see} +key set, but this will also show the rest of the \gls*{numberlist}. + +Another approach in this situation is to use the post description +hook with \cs{glsxtrusesee} to append the cross-reference after +the description. For example: +\begin{verbatim} +\renewcommand*{\glsxtrpostdescgeneral}{% + \ifglshasfield{see}{\glscurrententrylabel} + {, \glsxtrusesee{\glscurrententrylabel}}% + {}% +} +\end{verbatim} +Now the cross-references can appear even though the \gls{numberlist} +has been suppressed. + +As from v1.16, there's a separate \gloskey{seealso} key. Unlike +\gloskey{see}, this doesn't have an optional part for the textual +tag. The syntax \texttt{seealso=\marg{xr-labels}} works in much the same way as using +\texttt{see=[\cs{seealsoname}]\marg{xr-labels}} but the information +is stored in a separate field. If you need a different tag, use the +\gloskey{see} key instead (or redefine \cs{seealsoname} or +\cs{glsxtruseseealsoformat}, described below). + +You can display the formatted list of +cross-references stored in the \gloskey{seealso} key using: +\begin{definition}[\DescribeMacro\glsxtruseseealso] +\cs{glsxtruseseealso}\marg{label} +\end{definition} +This works in much the same way as \cs{glsxtrusesee} +but it internally uses +\begin{definition}[\DescribeMacro\glsxtruseseeformat] +\cs{glsxtruseseealsoformat}\marg{xr list} +\end{definition} +For example: +\begin{verbatim} +\renewcommand*{\glsxtrpostdescgeneral}{% + \ifglshasfield{see}{\glscurrententrylabel} + {, \glsxtrusesee{\glscurrententrylabel}}% + {}% + \ifglshasfield{seealso}{\glscurrententrylabel} + { (\glsxtruseseealso{\glscurrententrylabel})}% + {}% +} +\end{verbatim} + +The actual unformatted comma-separated list \meta{xr-list} +stored in the \gloskey{seealso} field can be accessed with: +\begin{definition}[\DescribeMacro\glsxtrseealsolabels] +\cs{glsxtrseealsolabels}\marg{label} +\end{definition} +This will just expand to the \meta{xr-labels} provided in the value +of the \gloskey{seealso} key. There's no corresponding command to +access the \gloskey{see} field. If you really need to access it, you +can use commands like \cs{glsxtrfielduse}, but remember that it +may start with \oarg{tag}, so it can't be automatically treated +as a simple comma-separated list. + +As mentioned above, the base \styfmt{glossaries} package provides \ics{glsseelist}, +which requires a comma-separated list of labels as the argument. +The argument isn't fully expanded, so it's not suitable to use, for +example, \cs{glsxtrseealsolabels}\marg{label} as the argument. +For convenience, \styfmt{glossaries-extra} provides +\begin{definition}[\DescribeMacro\glsxtrseelist] +\cs{glsxtrseelist}\marg{xr list} +\end{definition} +which fully expands its argument and passes it to \cs{glsseelist}. + +The \gloskey{seealso} key implements the automatic indexing using +\begin{definition}[\DescribeMacro\glsxtrindexseealso] +\cs{glsxtrindexseealso}\marg{label}\marg{xr list} +\end{definition} +which just does +\begin{alltt} +\cs{glssee}[\cs{seealsoname}]\marg{label}\marg{xr list} +\end{alltt} +unless the \pkgopt{xindy} option is used with \sty{glossaries} +v4.30+, in which case a distinct \texttt{seealso} cross-reference +class is used instead. + +\section{Entry Display Style Modifications} +\label{sec:entryfmtmods} + +Recall from the \styfmt{glossaries} package that commands such as \cs{gls} +display text at that point in the document (optionally with a +hyperlink to the relevant line in the glossary). This text is +referred to as the \qt{\gls{linktext}} regardless of whether or not it +actually has a hyperlink. The actual text and the way it's displayed +depends on the command used (such as \cs{gls}) and the entry format. + +The default entry format (\ics{glsentryfmt}) used in the +\gls{linktext} by commands like \ics{gls}, \ics{glsxtrfull}, +\ics{glsxtrshort} and \ics{glsxtrlong} (but not commands like +\ics{glslink}, \ics{glsfirst} and \cs{glstext}) is changed by \styfmt{glossaries-extra} to test for +regular entries, which are determined as follows: + +\begin{itemize} +\item If an entry is assigned to a category that has the +\catattr{regular} attribute set (see \sectionref{sec:categories}), the entry is considered a~regular +entry, even if it has a~value for the \gloskey{short} key. +In this case \cs{glsentryfmt} uses \ics{glsgenentryfmt} +(provided by \styfmt{glossaries}), which uses the \gloskey{first} +(or \gloskey{firstplural}) value on \gls{firstuse} and the +\gloskey{text} (or \gloskey{plural}) value on subsequent use. + +\item An entry that doesn't have a~value for the \gloskey{short} +key is assumed to be a~regular entry, even if the +\catattr{regular} attribute isn't set to \qt{true} (since it can't +be an abbreviation without the short form). +In this case \cs{glsentryfmt} uses \ics{glsgenentryfmt}. + +\item If an entry does has a~value for the \gloskey{short} key +and hasn't been marked as a~regular entry through the +\catattr{regular} attribute, it's not considered a regular entry. +In this case \cs{glsentryfmt} uses \ics{glsxtrgenabbrvfmt} +(defined by \styfmt{glossaries-extra}) which is governed +by the abbreviation style (see \sectionref{sec:abbrstyle}). + +\end{itemize} + +This means that entries with a short +form can be treated as regular entries rather than +abbreviations if it's more appropriate for the desired style. + +As from version 1.04, \ics{glsentryfmt} now puts \ics{glsgenentry} +in the argument of the new command +\begin{definition}[\DescribeMacro\glsxtrregularfont] +\cs{glsxtrregularfont}\marg{text} +\end{definition} +This just does its argument \meta{text} by default. This means that +if you want regular entries in a different font but don't want +that font to apply to abbreviations, then you can redefine +\cs{glsxtrregularfont}. This is more precise than changing +\ics{glstextformat} which is applied to all linking commands +for all entries, unless overridden by the \catattr{textformat} +attribute. + +For example: +\begin{verbatim} +\renewcommand*{\glsxtrregularfont}[1]{\textsf{#1}} +\end{verbatim} +You can access the label through \cs{glslabel}. For example, +you can query the category: +\begin{verbatim} +\renewcommand*{\glsxtrregularfont}[1]{% + \glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}} +\end{verbatim} +or query the category attribute, for example, provide a custom +attribute called \texttt{font}: +\begin{verbatim} +\glssetcategoryattribute{general}{font}{sf} + +\renewcommand*{\glsxtrregularfont}[1]{% + \glsifattribute{\glslabel}{font}{sf}{\textsf{#1}}{#1}} +\end{verbatim} +As from version 1.21, it's simpler to just do, for example: +\begin{verbatim} +\glssetcategoryattribute{general}{textformat}{textsf} +\end{verbatim} +without redefining \cs{glsxtrregularfont}. + +As from version 1.30, there is also a command for abbreviations +that encapsulates \cs{glsxtrgenabbrvfmt}: +\begin{definition}[\DescribeMacro\glsxtrabbreviationfont] +\cs{glsxtrabbreviationfont}\marg{text} +\end{definition} +This also just does its argument by default. Font changes +made by abbreviation styles are within \meta{text}. + +The \cs{glspostlinkhook} provided by the \styfmt{glossaries} package to +insert information after the \gls{linktext} produced by commands like \cs{gls} and \cs{glstext} is +redefined to +\begin{definition}[\DescribeMacro\glsxtrpostlinkhook] +\cs{glsxtrpostlinkhook} +\end{definition} +This command will discard a following full stop (period) if the +\catattr{discardperiod} attribute is set to \qt{true} for the +current entry's category. It will also do +\begin{definition}[\DescribeMacro\glsxtrpostlink] +\cs{glsxtrpostlink} +\end{definition} +if a full stop hasn't be discarded and +\begin{definition}[\DescribeMacro\glsxtrpostlinkendsentence] +\cs{glsxtrpostlinkendsentence} +\end{definition} +if a full stop has been discarded. + +It may be that you want to check some other setting (rather +than a category attribute) to determine whether or not to discard +a following full stop. In which case you can redefine: +\begin{definition}[\DescribeMacro\glsxtrifcustomdiscardperiod] +\cs{glsxtrifcustomdiscardperiod}\marg{true}\marg{false} +\end{definition} +You can access the field's label using \cs{glslabel}. +This command should do \meta{true} if the post-link hook +should check if a period follows and \meta{false} otherwise. +The default definition is simply: +\begin{verbatim} +\newcommand*{\glsxtrifcustomdiscardperiod}[2]{#2} +\end{verbatim} +which means that no additional checks are performed. +(Only the recognised category attributes will be checked.) + +\begin{important} +Avoid the use of \cs{gls}-like and \cs{glstext}-like commands +within the post-link hook as they will cause interference. +Consider using commands like \cs{glsentrytext}, \cs{glsaccesstext} +or \cs{glsxtrp} (\sectionref{sec:nested}) instead. +\end{important} + +By default \cs{glsxtrpostlink} just does \postlinkcat\ if it exists, where +\meta{category} is the category label for the current entry. +(For example, for the \category{general} category, +\cs{glsxtrpostlinkgeneral} if it has been defined.) + +You can define the post-link hook command using \cs{newcommand}, for +example: +\begin{verbatim} +\newcommand*{\glsxtrpostlinkgeneral}{% + \glsxtrpostlinkAddDescOnFirstUse +} +\end{verbatim} +or, as from v1.31, you can use +\begin{definition}[\DescribeMacro\glsdefpostlink] +\cs{glsdefpostlink}\marg{category}\marg{definition} +\end{definition} +This is simply a shortcut for: +\begin{alltt} +\cs{csdef}\{glsxtrpostlink\meta{category}\}\marg{definition} +\end{alltt} +Note that it doesn't check if the command has already been defined. + +\begin{sloppypar} +The sentence-ending hook is slightly more complicated. +If the command \postlinkcat\ is defined the hook will do that +and then insert a full stop with the space factor adjusted to match +the end of sentence. If \postlinkcat\ hasn't +been defined, the space factor is adjusted to match the end of +sentence. This means that if you have, for example, an entry that +ends with a full stop, a redundant following full stop will be +discarded and the space factor adjusted (in case the entry is in +uppercase) unless the entry is followed by additional material, in +which case the following full stop is no longer redundant and needs +to be reinserted. +\end{sloppypar} + +There are some convenient commands you might want to use +when customizing the post-\gls{linktext} category hooks: +\begin{definition}[\DescribeMacro\glsxtrpostlinkAddDescOnFirstUse] +\cs{glsxtrpostlinkAddDescOnFirstUse} +\end{definition} +This will add the description in parentheses on \gls{firstuse}. + +For example, suppose you want to append the description in +parentheses on \gls{firstuse} for entries in the \category{symbol} +category: +\begin{verbatim} +\newcommand*{\glsxtrpostlinksymbol}{% + \glsxtrpostlinkAddDescOnFirstUse +} +\end{verbatim} + +\begin{definition}[\DescribeMacro\glsxtrpostlinkAddSymbolOnFirstUse] +\cs{glsxtrpostlinkAddSymbolOnFirstUse} +\end{definition} +This will append the symbol (if defined) in parentheses on +\gls{firstuse}. (Does nothing if the symbol hasn't been set.) + +\begin{definition}[\DescribeMacro\glsxtrpostlinkAddSymbolDescOnFirstUse] +\cs{glsxtrpostlinkAddSymbolDescOnFirstUse} +\end{definition} +(New to v1.31.) On \gls{firstuse}, +this will append \cs{space}(\meta{symbol}, \meta{description}) if +the symbol is defined otherwise it just appends +\cs{space}(\meta{description}). + +If you want to provide your own custom format be aware that you +can't use \ics{ifglsused} within the post-\gls{linktext} hook as by this point +the \gls{firstuseflag} will have been unset. Instead you can use +\begin{definition}[\DescribeMacro\glsxtrifwasfirstuse] +\cs{glsxtrifwasfirstuse}\marg{true}\marg{false} +\end{definition} +This will do \meta{true} if the last used entry was the +\gls{firstuse} +for that entry, otherwise it will do \meta{false}. (Requires at +least \styfmt{glossaries} v4.19 to work properly.) This command is +locally set by commands like \cs{gls}, so don't rely on it outside +of the post-\gls{linktext} hook. + +\begin{important} +Note that commands like \ics{glsfirst} and \ics{glsxtrfull} fake +\gls{firstuse} for the benefit of the post-\gls{linktext} hooks by setting +\cs{glsxtrifwasfirstuse} to \cs{@firstoftwo}. +(Although, depending on the styles in use, they may not exactly match +the text produced by \ics{gls}-like commands on \gls{firstuse}.) +However, the \abbrstyle{short-postfootnote} style alters \cs{glsxtrfull} +so that it fakes non-\gls{firstuse} otherwise the inline full format +would include the footnote, which is inappropriate. +\end{important} + +For example, if you want to place the description in a footnote +after the \gls{linktext} on \gls{firstuse} for the \category{general} category: +\begin{verbatim} +\newcommand*{\glsxtrpostlinkgeneral}{% + \glsxtrifwasfirstuse{\footnote{\glsentrydesc{\glslabel}}}{}% +} +\end{verbatim} + +The \abbrstyle{short-postfootnote} abbreviation style uses the +post-\gls{linktext} hook to +place the footnote after trailing punctuation characters. + +You can set the default options used by \ics{glslink}, \ics{gls} +etc with: +\begin{definition}[\DescribeMacro\GlsXtrSetDefaultGlsOpts] +\cs{GlsXtrSetDefaultGlsOpts}\marg{options} +\end{definition} +For example, if you mostly don't want to index entries then +you can do: +\begin{verbatim} +\GlsXtrSetDefaultGlsOpts{noindex} +\end{verbatim} +and then use, for example, \verb|\gls[noindex=false]{sample}| +when you actually want the location added to the \gls{numberlist}. +These defaults may be overridden by other settings (such as +category attributes) in addition to any settings passed in the +option argument of commands like \cs{glslink} and \cs{gls}. + +Note that if you don't want \emph{any} indexing, just omit +\cs{makeglossaries} and \cs{printglossaries} (or analogous +commands). If you want to adjust the default for +\gloskey[glslink]{wrgloss}, it's better to do this by redefining +\ics{glsxtrinitwrgloss} instead. + +\begin{important} +\cs{GlsXtrSetDefaultGlsOpts} doesn't affect \cs{glsadd}. +\end{important} + +If you want to change the default value of \gloskey[glsadd]{format}, +you can instead use: +\begin{definition}[\GlsXtrSetDefaultNumberFormat] +\cs{GlsXtrSetDefaultNumberFormat}\marg{format} +\end{definition} +This has the advantage of also working for \cs{glsadd}. +For example, if you want all locations in the back matter to appear +in italic (unless explicitly overridden): +\begin{verbatim} +\backmatter +\GlsXtrSetDefaultNumberFormat{hyperit} +\end{verbatim} + +Commands like \ics{gls} have star (\texttt{*}) and plus +(\texttt{+}) modifiers as a short cut for \texttt{hyper=false} +and \texttt{hyper=true}. The \styfmt{glossaries-extra} package +provides a way to add a third modifier, if required, using +\begin{definition}[\DescribeMacro\GlsXtrSetAltModifier] +\cs{GlsXtrSetAltModifier}\marg{char}\marg{options} +\end{definition} +where \meta{char} is the character used as the modifier and +\meta{options} is the default set of options (which may be +overridden). Note that \meta{char} must be a single character +(not a UTF-8 character, unless you are using \XeLaTeX\ or +\LuaLaTeX). + +\begin{important} +When choosing the character \meta{char} take care of any +changes in category code. +\end{important} + +Example: +\begin{verbatim} +\GlsXtrSetAltModifier{!}{noindex} +\end{verbatim} +This means that \verb|\gls!{sample}| will be equivalent to +\verb|\gls[noindex]{sample}|. It's not possible to mix modifiers. +For example, if you want to do +\begin{verbatim} +\gls[noindex,hyper=false]{sample} +\end{verbatim} +you can use \verb|\gls*[noindex]{sample}| or +\verb|\gls![hyper=false]{sample}| but you can't combine the +\texttt{*} and \texttt{!} modifiers. + +\Glspl{locationlist} displayed with \cs{printnoidxglossary} +internally use +\begin{definition}[\DescribeMacro\glsnoidxdisplayloc] +\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location} +\end{definition} +This command is provided by \styfmt{glossaries}, but is modified by +\styfmt{glossaries-extra} to check for the start and end range +formation identifiers \verb|(| and \verb|)| which are discarded to +obtain the actual control sequence name that forms the location +formatting command. + +If the range identifiers aren't present, this just uses +\begin{definition}[\DescribeMacro\glsxtrdisplaysingleloc] +\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location} +\end{definition} +otherwise it uses +\begin{definition}[\DescribeMacro\glsxtrdisplaystartloc] +\cs{glsxtrdisplaystartloc}\marg{format}\marg{location} +\end{definition} +for the start of a range (where the identifier has been stripped +from \meta{format}) or +\begin{definition}[\DescribeMacro\glsxtrdisplayendloc] +\cs{glsxtrdisplayendloc}\marg{format}\marg{location} +\end{definition} +for the end of a range (where the identifier has been stripped +from \meta{format}). + +By default the start range command saves the format in +\begin{definition}[\DescribeMacro\glsxtrlocrangefmt] +\cs{glsxtrlocrangefmt} +\end{definition} +and does +\begin{display} +\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location} +\end{display} +(If the format is empty, it will be replaced with +\texttt{glsnumberformat}.) + +The end command checks that the format matches the start of the +range, does +\begin{definition}[\DescribeMacro\glsxtrdisplayendlochook] +\cs{glsxtrdisplayendlochook}\marg{format}\marg{location} +\end{definition} +(which does nothing by default), followed by +\begin{display} +\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location} +\end{display} +and then sets \cs{glsxtrlocrangefmt} to empty. + +This means that the list +\begin{verbatim} +\glsnoidxdisplayloc{}{page}{(textbf}{1}, +\glsnoidxdisplayloc{}{page}{textbf}{1}, +\glsnoidxdisplayloc{}{page}{)textbf}{1}. +\end{verbatim} +doesn't display any differently from +\begin{verbatim} +\glsnoidxdisplayloc{}{page}{textbf}{1}, +\glsnoidxdisplayloc{}{page}{textbf}{1}, +\glsnoidxdisplayloc{}{page}{textbf}{1}. +\end{verbatim} +but it does make it easier to define your own custom list handler +that can accommodate the ranges. + + +\section{Entry Counting Modifications} +\label{sec:entrycountmods} + +If you are using \gls{bib2gls} you may find it more convenient +to use the record count commands described in +\sectionref{sec:bib2gls} instead. + +The \ics{glsenableentrycount} command is modified to allow +for the \catattr{entrycount} attribute. This means that +you not only need to enable entry counting with +\cs{glsenableentrycount}, but you also need +to set the appropriate attribute (see \sectionref{sec:categories}). + +For example, instead of just doing: +\begin{verbatim} +\glsenableentrycount +\end{verbatim} +you now need to do: +\begin{verbatim} +\glsenableentrycount +\glssetcategoryattribute{abbreviation}{entrycount}{1} +\end{verbatim} +This will enable the entry counting for entries in the +\category{abbreviation} category, but any entries assigned to +other categories will be unchanged. + +Further information about entry counting, including the +new per-unit feature, is described in \sectionref{sec:entrycount}. + +\section{First Use Flag} +\label{sec:glsunset} + +The \styfmt{glossaries} package provides +\begin{definition} +\ics{ifglsused}\marg{label}\marg{true}\marg{false} +\end{definition} +to determine whether or not an entry has been used. This requires +the entry to have been defined. If the entry is undefined, then the +underlying boolean variable doesn't exist and so is neither true +nor false. This command will produce an error with the default +\pkgopt[error]{undefaction} mode and a warning with +\pkgopt[warn]{undefaction} and, where appropriate, displays ?? in +the document text to denote an undefined reference. With both modes, +neither \meta{true} nor \meta{false} will be performed if +\meta{label} doesn't exist. + +The \pkgopt{record} option automatically implements +\pkgopt[warn]{undefaction} since no entries will be defined until +they have been selected by \gls{bib2gls}. In this case, you +may prefer to use: +\begin{definition}[\DescribeMacro\GlsXtrIfUnusedOrUndefined] +\cs{GlsXtrIfUnusedOrUndefined}\marg{label}\marg{true}\marg{false} +\end{definition} +(new to v1.34) which does \meta{true} if the entry given by +\meta{label} is undefined or if the entry is marked as unused. +Remember that neither \cs{ifglsused} nor +\cs{GlsXtrIfUnusedOrUndefined} should be used in the post-link +hook as the \gls{firstuseflag} will have already been unset +before the hook is performed. (Instead, \ics{glsxtrifwasfirstuse} +should be used, see \sectionref{sec:entryfmtmods}.) + +There are two new commands provided with version 1.31+: +\begin{definition}[\DescribeMacro\glslocalreseteach] +\cs{glslocalreseteach}\marg{list} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslocalunseteach] +\cs{glslocalunseteach}\marg{list} +\end{definition} +These behave like \cs{glslocalreset} and \cs{glslocalunset} +but the argument is a comma-separated list of labels. + +The internal command used by \cs{glsunset} is modified first to +allow for the changing in entry counting, described above, but +also to allow for buffering pending unsets when commands like +\cs{gls} are used in a context where changing a boolean variable +can cause things to go wrong. One example of this is using +\cs{gls} in one of the commands provided with the \isty{soul} +package. For example: +\begin{verbatim} +\ul{Some text about \gls{html}.} +\end{verbatim} +This causes the confusing error: +\begin{verbatim} +Glossary entry `{html}' has not been defined. +\end{verbatim} +The simplest workaround is to put \verb|\gls{html}| inside the +argument of \cs{mbox}. For example: +\begin{verbatim} +\ul{Some text about \mbox{\gls{html}}.} +\end{verbatim} +This can work provided it's not the first use of this entry. +It if is, then unsetting the first use flag causes a problem +and results in the error: +\begin{verbatim} +! Package soul Error: Reconstruction failed. +\end{verbatim} +The \styfmt{glossaries-extra} package provides a way of temporarily +switching off \cs{glsunset} so that it just makes a note of the +entry's label but doesn't actually perform the change: +\begin{definition}[\DescribeMacro\GlsXtrStartUnsetBuffering] +\cs{GlsXtrStartUnsetBuffering} +\end{definition} +The unstarred version doesn't check for duplicates, so the internal +list may end up with multiple occurrences of the same label. The +starred version only adds a label to the internal list if it's not +already in it. Note that this buffering only applies to the +global \cs{glsunset} and does not affect the local +\cs{glslocalunset}. + +Later you can restore \cs{glsunset} and unset all buffered +labels using: +\begin{definition}[\DescribeMacro\GlsXtrStopUnsetBuffering] +\cs{GlsXtrStopUnsetBuffering} +\end{definition} +The starred form \cs{GlsXtrStopUnsetBuffering*} uses +\cs{glslocalunset} instead. For example: +\begin{verbatim} +\documentclass{article} + +\usepackage[T1]{fontenc} +\usepackage{soul} +\usepackage{glossaries-extra} + +\newabbreviation{html}{HTML}{hypertext markup language} + +\begin{document} +\GlsXtrStartUnsetBuffering +\ul{Some text about \mbox{\gls{html}}.} +\GlsXtrStopUnsetBuffering + +Next use: \gls{html}. +\end{document} +\end{verbatim} +Before you stop the unset buffering, you can iterate over the +current buffer using +\begin{definition}[\DescribeMacro\GlsXtrForUnsetBufferedList] +\cs{GlsXtrForUnsetBufferedList}\marg{cs} +\end{definition} +where \meta{cs} is a control sequence that takes a single argument +(which is the entry label). This is best used with the starred +version \cs{GlsXtrStartUnsetBuffering*} to avoid duplicates. + +\begin{important} +Note that since the change in the first use flag now doesn't +occur until \cs{GlsXtrStopUnsetBuffering}, multiple references +of the same term within the buffering zone will always be +treated as first use (if the term wasn't used before the +buffering started). +\end{important} + +There can still be a problem here as content within \cs{mbox} +can't break across a line so you may end up with an overfull +line or excessive white space within the paragraph. + +An alternative is to use \cs{protect}: +\begin{verbatim} +\GlsXtrStartUnsetBuffering +\ul{Some text about \protect\gls{html}.} +\GlsXtrStopUnsetBuffering +\end{verbatim} +but the formatting (underlining in this example) won't be applied. +Another possibility is: +\begin{verbatim} +\usepackage[T1]{fontenc} +\usepackage{soul} +\usepackage{glossaries-extra} + +\newabbreviation{html}{HTML}{hypertext markup language} + +\newrobustcmd{\gul}[1]{% + {% + \def\glsxtrabbreviationfont##1{\GlsXtrExpandedFmt{\ul}{##1}}% + \def\glsxtrregularfont##1{\GlsXtrExpandedFmt{\ul}{##1}}% + #1% + }% +} + +\begin{document} +\ul{Some text about }\gls[textformat=gul]{html}. + +Next use: \gls{html}. +\end{document} +\end{verbatim} +This moves \cs{gls} outside of \cs{ul} and uses +\gloskey[glslink]{textformat} to locally change the formatting +command used by \cs{gls} (which is normally given by +\cs{glstextformat} or the \catattr{textformat} attribute) +to a custom command \cs{gul}, which locally changes the regular font +and the default abbreviation font to use \cs{ul}. It then uses +\begin{definition}[\DescribeMacro\GlsXtrExpandedFmt] +\cs{GlsXtrExpandedFmt}\marg{cs}\marg{text} +\end{definition} +which (protected) fully expands \meta{text} before applying +\meta{cs}, which must be a control sequence that takes a single +argument. This allows \cs{ul} to move much further inside +and increases its chances of working. It can still break if +\meta{text} expands to something that \cs{ul} can't deal with. +For example, if an abbreviation style is used that contains +complex formatting or if the field value contains problematic +content. + +\section{Plurals} + +Some languages, such as English, have a general rule that plurals +are formed from the singular with a suffix appended. This isn't +an absolute rule. There are plenty of exceptions (for example, +geese, children, churches, elves, fairies, sheep). The +\sty{glossaries} package allows the \gloskey{plural} key to be +optional when defining entries. In some cases a plural may not make +any sense (for example, the term is a symbol) and in some cases +the plural may be identical to the singular. + +To make life easier for languages where the majority of plurals can +simply be formed by appending a suffix to the singular, the +\sty{glossaries} package lets the \gloskey{plural} field default +to the value of the \gloskey{text} field with \ics{glspluralsuffix} +appended. This command is defined to be just the letter \qt{s}. +This means that the majority of terms don't need to have the +\gloskey{plural} supplied as well, and you only need to use it for the +exceptions. + +For languages that don't have this general rule, the \gloskey{plural} +field will always need to be supplied, where needed. + +There are other plural fields, such as \gloskey{firstplural}, +\gloskey{longplural} and \gloskey{shortplural}. Again, if you are using +a language that doesn't have a simple suffix rule, you'll have to +supply the plural forms if you need them (and if a plural makes +sense in the context). + +If these fields are omitted, the \sty{glossaries} package follows +these rules: +\begin{itemize} +\item If \gloskey{firstplural} is missing, then \cs{glspluralsuffix} +is appended to the \gloskey{first} field, if that field has been +supplied. If the \gloskey{first} field hasn't been supplied but the +\gloskey{plural} field has been supplied, then the \gloskey{firstplural} +field defaults to the \gloskey{plural} field. If the \gloskey{plural} +field hasn't been supplied, then both the \gloskey{plural} and +\gloskey{firstplural} fields default to the \gloskey{text} field (or +\gloskey{name}, if no \gloskey{text} field) with \cs{glspluralsuffix} +appended. + +\item If the \gloskey{longplural} field is missing, then +\cs{glspluralsuffix} is appended to the \gloskey{long} field, if the +\gloskey{long} field has been supplied. + +\item If the \gloskey{shortplural} field is missing then, \emph{with +the base \sty{glossaries} acronym mechanism}, \ics{acrpluralsuffix} +is appended to the \gloskey{short} field. + +\end{itemize} + +This \emph{last case is changed} with \styfmt{glossaries-extra}. +With this extension package, the \gloskey{shortplural} field +defaults to the \gloskey{short} field with \ics{abbrvpluralsuffix} +appended unless overridden by category attributes. This +suffix command is set by the abbreviation styles. This means that +every time an abbreviation style is implemented, +\cs{abbrvpluralsuffix} is redefined. In most cases its redefined to +use +\begin{definition}[\DescribeMacro\glsxtrabbrvpluralsuffix] +\cs{glsxtrabbrvpluralsuffix} +\end{definition} +which defaults to just \cs{glspluralsuffix}. Some of the +abbreviation styles have their own command for the plural suffix, +such as \cs{glsxtrscsuffix}, +so if you want to completely strip all the plural suffixes used for +abbreviations then you need to redefine \cs{glsxtrabbrvpluralsuffix} +\emph{not} \cs{abbrvpluralsuffix}, which changes with the style. Redefining +\cs{acrpluralsuffix} will have no affect, since it's not used by the +new abbreviation mechanism. + +If you require a mixture (for example, in a multilingual document), +there are two attributes that affect the short plural suffix +formation. The first is \catattr{aposplural} which uses the suffix +\begin{verbatim} +'\abbrvpluralsuffix +\end{verbatim} +That is, an apostrophe followed by \cs{abbrvpluralsuffix} is +appended. The second attribute is \catattr{noshortplural} which +suppresses the suffix and simply sets \gloskey{shortplural} to the +same as \gloskey{short}. + +\section{Nested Links} +\label{sec:nested} + +Complications arise when you use \ics{gls} in the +value of the \gloskey{name} field (or \gloskey{text} +or \gloskey{first} fields, if set). This tends to occur with +abbreviations that extend other abbreviations. For example, +SHTML is an abbreviation for SSI enabled HTML, where SSI +is an abbreviation for Server Side Includes and HTML +is an abbreviation for Hypertext Markup Language. + +Things can go wrong if we try the following with the +\styfmt{glossaries} package: +\begin{verbatim} +\newacronym{ssi}{SSI}{Server Side Includes} +\newacronym{html}{HTML}{Hypertext Markup Language} +\newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}} +\end{verbatim} + +The main problems are: +\begin{enumerate} +\item\label{itm:nestedfirstucprob} The first letter upper casing commands, such as \ics{Gls}, +won't work for the \texttt{shtml} entry on \gls{firstuse} if the +long form is displayed before the short form (which is the +default abbreviation style). This will attempt to do +\begin{verbatim} +\gls{\uppercase ssi} enabled \gls{html} +\end{verbatim} +which just doesn't work. Grouping the \verb|\gls{ssi}| doesn't +work either as this will effectively try to do +\begin{verbatim} +\uppercase{\gls{ssi}} enabled \gls{html} +\end{verbatim} +This will upper case the label \texttt{ssi} so the entry won't be +recognised. This problem will also occur if you use the all capitals +version, such as \ics{GLS}. + +\item\label{itm:nonexpandprob} The long and abbreviated forms accessed through +\ics{glsentrylong} and \ics{glsentryshort} are no longer expandable +and so can't be used be used in contexts that require this, +such as PDF bookmarks. + +\item\label{itm:nestedsortprob} The nested commands may end up in the \gloskey{sort} key, +which will confuse the indexing. + +\item\label{itm:inconsistentfirstuseprob} The \texttt{shtml} entry produces inconsistent results +depending on whether the \texttt{ssi} or \texttt{html} entries have +been used. Suppose both \texttt{ssi} and \texttt{html} are used +before \texttt{shtml}. For example: +\begin{verbatim} +This section discusses \gls{ssi}, \gls{html} and \gls{shtml}. +\end{verbatim} +This produces: +\begin{quote} +This section discusses server side includes (SSI), hypertext markup +language (HTML) and SSI enabled HTML (SHTML). +\end{quote} +So the \gls{firstuse} of the \texttt{shtml} entry produces +\qt{SSI enabled HTML (SHTML)}. + +Now let's suppose the \texttt{html} entry is used before the +\texttt{shtml} but the \texttt{ssi} entry is used after the +\texttt{shtml} entry, for example: +\begin{verbatim} +The sample files are either \gls{html} or \gls{shtml}, but let's +first discuss \gls{ssi}. +\end{verbatim} +This produces: +\begin{quote} +The sample files are either hypertext markup language (HTML) or +server +side includes (SSI) enabled HTML (SHTML), but let's first discuss +SSI. +\end{quote} +So the \gls{firstuse} of the \texttt{shtml} entry now produces +\qt{server side includes (SSI) enabled HTML (SHTML)}, which looks +a bit strange. + +Now let's suppose the \texttt{shtml} entry is used before (or +without) the other two entries: +\begin{verbatim} +This article is an introduction to \gls{shtml}. +\end{verbatim} +This produces: +\begin{quote} +This article is an introduction to server side includes (SSI) +enabled hypertext markup language (HTML) (SHTML). +\end{quote} +So the \gls{firstuse} of the \texttt{shtml} entry now produces +\qt{server side includes (SSI) enabled hypertext markup language (HTML) +(SHTML)}, which is even more strange. + +This is all aggravated by setting the style using the +\styfmt{glossaries} package's +\cs{setacronymstyle}. For example: +\begin{verbatim} +\setacronymstyle{long-short} +\end{verbatim} +as this references the label through the use of \cs{glslabel} +when displaying the long and short forms, but this value +changes with each use of \cs{gls}, so instead of displaying +\qt{(SHTML)} at the end of the \gls{firstuse}, it now displays +\qt{(HTML)}, since \cs{glslabel} has been changed to \texttt{html} +by \verb|\gls{html}|. + +Another oddity occurs if you reset the \texttt{html} entry between +uses of the \texttt{shtml} entry. For example: +\begin{verbatim} +\gls{shtml} ... \glsreset{html}\gls{shtml} +\end{verbatim} +The next use of \texttt{shtml} produces \qt{Shypertext markup +language (HTML)}, which is downright weird. + +Even without this, the short form has nested formatting commands, +which amount to \verb|\acronymfont{S\acronymfont{HTML}}|. This +may not be a problem for some styles, but if you use one of the +\qt{sm} styles (that use \ics{textsmaller}), this will produce +an odd result. + +\item\label{itm:indexingprob} Each time the \texttt{shtml} entry is used, the +\texttt{html} entry will also be indexed and marked as used, +and on \gls{firstuse} this will happen to both the \texttt{ssi} +and \texttt{html} entries. This kind of duplication in the location +list isn't usually particularly helpful to the reader. + +\item\label{itm:nestedhyplinkprob} If \sty{hyperref} is in use, you'll get nested hyperlinks +and there's no consistent way of dealing with this across the +available PDF viewers. If on the \gls{firstuse} case, the user +clicks on the \qt{HTML} part of the \qt{SSI enabled HTML (SHTML)} +link, they may be directed to the HTML entry in the glossary or +they may be directed to the SHTML entry in the glossary. + +\end{enumerate} + +For these reasons it's better to use the simple expandable commands like +\ics{glsentrytext} or \ics{glsentryshort} in the definition +of other entries (although that doesn't fix the first problem). +Alternatively use something like: +\begin{verbatim} +\newacronym + [description={\acrshort{ssi} enabled \acrshort{html}}] + {shtml}{SHTML}{SSI enabled HTML} +\end{verbatim} +with \styfmt{glossaries} or: +\begin{verbatim} +\newabbreviation + [description={\glsxtrshort{ssi} enabled \glsxtrshort{html}}] + {shtml}{SHTML}{SSI enabled HTML} +\end{verbatim} +with \styfmt{glossaries-extra}. This fixes all the above +listed problems (as long as you don't use \ics{glsdesc}). +Note that replacing \cs{gls} with \cs{acrshort} in the original +example may fix the \gls{firstuse} issue, but it doesn't +fix any of the other problems listed above. + +If it's simply that you want to use the abbreviation font, you can +use \cs{glsabbrvfont}: +\begin{verbatim} +\setabbreviationstyle{long-short-sc} + +\newabbreviation{ssi}{ssi}{server-side includes} +\newabbreviation{html}{html}{hypertext markup language} +\newabbreviation{shtml}{shtml}{\glsabbrvfont{ssi} enabled +\glsabbrvfont{html}} +\end{verbatim} +This will pick up the font style setting of the outer entry (shtml, +in the above case). This isn't a problem in the above example as all +the abbreviations use the same style. + +However if you're really determined to use +\ics{gls} in a field that may be included within +some \gls{linktext}, \styfmt{glossaries-extra} patches internals +used by the linking commands so that if \cs{gls} (or plural or +case changing variants) occurs in the \gls{linktext} it will +behave as though you used +\texttt{\ics{glstext}[hyper=false,noindex]} +instead. Grouping is also added so that, for example, when +\verb|\gls{shtml}| is used for the first time the long form +\begin{verbatim} +\gls{ssi} enabled \gls{html} +\end{verbatim} +is treated as +\begin{verbatim} +{\glstext[hyper=false,noindex]{ssi}} enabled +{\glstext[hyper=false,noindex]{html}} +\end{verbatim} +This overcomes problems~\ref{itm:inconsistentfirstuseprob}, +\ref{itm:indexingprob} and \ref{itm:nestedhyplinkprob} listed +above, but still doesn't fix problems~\ref{itm:nestedfirstucprob} +and \ref{itm:nonexpandprob}. +Problem~\ref{itm:nestedsortprob} usually won't be an issue as most abbreviation +styles set the \gloskey{sort} key to the short form, so using these +commands in the long form but not the short form will only affect +entries with a style that sorts according to the long form (such as +\abbrstyle{long-noshort-desc}). + +Additionally, any instance of the long form commands, such +as \ics{glsxtrlong} or \ics{acrlong} will be temporarily +redefined to just use +\begin{alltt} +\{\ics{glsentrylong}\marg{label}\meta{insert}\} +\end{alltt} +(or case-changing versions). Similarly the short form commands, +such as \ics{glsxtrshort} or \ics{acrshort} will use +\ics{glsentryshort} in the argument of either \cs{glsabbrvfont} +(for \cs{glsxtrshort}) or \cs{acronymfont} (for \cs{acrshort}). +So if the \texttt{shtml} entry had instead been defined as: +\begin{verbatim} +\newacronym{shtml}{SHTML}{\acrshort{ssi} enabled \acrshort{html}} +\end{verbatim} +then (using the \abbrstyle{long-short} style) the \gls{firstuse} +will be like +\begin{verbatim} +{\acronymfont{\glsentryshort{ssi}}} enabled +{\acronymfont{\glsentryshort{html}}} (SHTML) +\end{verbatim} +whereas if the entry is defined as: +\begin{verbatim} +\newabbreviation{shtml}{SHTML}{\glsxtrshort{ssi} enabled +\glsxtrshort{html}} +\end{verbatim} +then the \gls{firstuse} will be like: +\begin{verbatim} +{\glsabbrvfont{\glsentryshort{ssi}}} enabled +{\glsabbrvfont{\glsentryshort{html}}} (SHTML) +\end{verbatim} +Note that the first optional argument of +\cs{acrshort} or \cs{glsxtrshort} is ignored in this context. +(The final optional argument will be inserted, if present.) +The abbreviation style that governs \ics{glsabbrvfont} will be +set for \ics{glsxtrshort}. Note that \cs{acrshort} doesn't +set the abbreviation style. + +Alternatively you can use: +\begin{definition}[\DescribeMacro\glsxtrp] +\cs{glsxtrp}\marg{field}\marg{label} +\end{definition} +where \meta{field} is the field label and corresponds to a +command in the form \cs{gls}\meta{field} (e.g.\ \cs{glstext}) or +in the form \cs{glsxtr}\meta{field} (e.g.\ \cs{glsxtrshort}). + +There's a shortcut command for the most common fields: +\begin{definition}[\DescribeMacro\glsps] +\cs{glsps}\marg{label} +\end{definition} +which is equivalent to \verb|\glsxtrp{short}|\marg{label}, and +\begin{definition}[\DescribeMacro\glspt] +\cs{glspt}\marg{label} +\end{definition} +which is equivalent to \verb|\glsxtrp{text}|\marg{label}. + +The \cs{glsxtrp} command behaves much like the +\cs{glsfmt}\meta{field} commands described in +\sectionref{sec:headtitle} but the post-link hook is also +suppressed and extra grouping is added. It automatically sets +\gloskey[glslink]{hyper} to \texttt{false} and +\gloskey[glslink]{noindex} to \texttt{true}. If you want to change +this, you can use +\begin{definition}[\DescribeMacro\glsxtrsetpopts] +\cs{glsxtrsetpopts}\marg{options} +\end{definition} +For example: +\begin{verbatim} +\glsxtrsetpopts{hyper=false} +\end{verbatim} +will just switch off the hyperlinks but not the indexing. +Be careful using this command or you can end up back to the +original problem of nested links. + +The hyper link is re-enabled within glossaries. This is +done through the command: +\begin{definition}[\DescribeMacro\glossxtrsetpopts] +\cs{glossxtrsetpopts} +\end{definition} +which by default just does +\begin{verbatim} +\glsxtrsetpopts{noindex} +\end{verbatim} +You can redefine this if you want to adjust the setting when +\cs{glsxtrp} is used in the glossary. For example: +\begin{verbatim} +\renewcommand{\glossxtrsetpopts}{\glsxtrsetpopts{noindex=false}} +\end{verbatim} + +For example, +\begin{verbatim} +\glsxtrp{short}{ssi} +\end{verbatim} +is equivalent to +\begin{verbatim} +{\let\glspostlinkhook\relax + \glsxtrshort[hyper=false,noindex]{ssi}[]% +} +\end{verbatim} +in the main body of the document or +\begin{verbatim} +{\let\glspostlinkhook\relax + \glsxtrshort[noindex]{ssi}[]% +} +\end{verbatim} +inside the glossary. (Note the post-link hook is locally disabled.) + +If \verb|\glsxtrp{short}{ssi}| occurs in a sectioning mark, +it's equivalent to +\begin{verbatim} +{\glsxtrheadshort{ssi}} +\end{verbatim} +(which recognises the \catattr{headuc} attribute.) + +If \sty{hyperref} has been loaded, then the bookmark will +use \cs{glsentry}\meta{field} +(\verb|\glsentryshort{ssi}| in the above example). + +There are similar commands +\begin{definition}[\DescribeMacro\Glsxtrp] +\cs{Glsxtrp}\marg{field}\marg{label} +\end{definition} +for first letter upper case and +\begin{definition}[\DescribeMacro\GLSxtrp] +\cs{GLSxtrp}\marg{field}\marg{label} +\end{definition} +for all upper case. + +\begin{important} +If you use any of the case-changing commands, such as \ics{Gls} +or \ics{Glstext}, (either all caps or first letter upper casing) +don't use any of the linking commands, such as \ics{gls} or +\ics{glstext}, in the definition of entries for any of the +fields that may be used by those case-changing commands. +\end{important} + +You can, with care, protect against issue~\ref{itm:nestedfirstucprob} by +inserting an empty group at the start if the long form starts with a +command that breaks the first letter uppercasing commands like +\cs{Gls}, but you still won't be able to use the all caps commands, +such as \cs{GLS}. + +If you \emph{really need} nested commands, the safest method is +\begin{verbatim} +\newabbreviation{shtml}{shtml}{{}\glsxtrp{short}{ssi} enabled +\glsxtrp{short}{html}} +\end{verbatim} +but be aware that it may have some unexpected results occasionally. + +Example document: +\begin{verbatim} +\documentclass{report} + +\usepackage[utf8]{inputenc} +\usepackage[T1]{fontenc} +\usepackage{slantsc} +\usepackage[colorlinks]{hyperref} +\usepackage[nopostdot=false]{glossaries-extra} + +\makeglossaries + +\setabbreviationstyle{long-short-sc} + +\newabbreviation{ssi}{ssi}{server-side includes} +\newabbreviation{html}{html}{hypertext markup language} +\newabbreviation{shtml}{shtml}{{}\glsps{ssi} enabled {}\glsps{html}} + +\pagestyle{headings} + +\glssetcategoryattribute{abbreviation}{headuc}{true} +\glssetcategoryattribute{abbreviation}{glossdesc}{title} + +\begin{document} + +\tableofcontents + +\chapter{\glsfmtfull{shtml}} + +First use: \gls{shtml}, \gls{ssi} and \gls{html}. + +Next use: \gls{shtml}, \gls{ssi} and \gls{html}. + +\newpage +Next page. + +\printglossaries +\end{document} +\end{verbatim} + +\section{Acronym Style Modifications} +\label{sec:acronymmods} + +The \styfmt{glossaries-extra} package provides a new way of dealing +with abbreviations and redefines \ics{newacronym} to +use \cs{newabbreviation} (see \sectionref{sec:abbreviations}). +The simplest way to update a document that uses +\cs{newacronym} from \styfmt{glossaries} to +\styfmt{glossaries-extra} is do just add +\begin{verbatim} +\setabbreviationstyle[acronym]{long-short} +\end{verbatim} +before you define any entries. +For example, the following document using just \styfmt{glossaries} +\begin{verbatim} +\documentclass{article} +\usepackage[acronym,nopostdot,toc]{glossaries} +\makeglossaries +\setacronymstyle{long-short} +\newacronym{html}{HTML}{hypertext markup language} +\begin{document} +\gls{html} +\printglossaries +\end{document} +\end{verbatim} +can be easily adapted to use \styfmt{glossaries-extra}: +\begin{verbatim} +\documentclass{article} +\usepackage[acronym]{glossaries-extra} +\makeglossaries +\setabbreviationstyle[acronym]{long-short} +\newacronym{html}{HTML}{hypertext markup language} +\begin{document} +\gls{html} +\printglossaries +\end{document} +\end{verbatim} +Table~\ref{tab:acrabbrvstyles} lists the nearest equivalent +\styfmt{glossaries-extra} abbreviation styles for +the predefined acronym styles provided by \styfmt{glossaries}, but +note that the new styles use different formatting commands. See +\sectionref{sec:predefabbrvstyles} for further details. + +\begin{table}[htbp] +\caption[Old Acronym Styles Verses New Abbreviation Styles]{Old Acronym Styles +\cs{setacronymstyle}\marg{old-style-name} Verses New Abbreviation +Styles \cs{setabbreviationstyle}\oarg{category}\marg{new-style-name}} +\label{tab:acrabbrvstyles} +\centering +\begin{tabular}{@{}p{\dimexpr0.3\textwidth-2\tabcolsep}p{0.7\textwidth}@{}} +\bfseries Old Style Name & +\bfseries New Style Name\\ +\acrstyle{long-sc-short} & \abbrstyle{long-short-sc}\\ +\acrstyle{long-sm-short} & \abbrstyle{long-short-sm}\\ +\acrstyle{long-sp-short} & \abbrstyle{long-short} \newline with +\ttfamily\cs{renewcommand}\{\cs{glsxtrfullsep}\}[1]\{\cs{glsacspace}\{\#1\}\}\\ +\acrstyle{short-long} & \abbrstyle{short-long}\\ +\acrstyle{sc-short-long} & \abbrstyle{short-sc-long}\\ +\acrstyle{sm-short-long} & \abbrstyle{short-sm-long}\\ +\acrstyle{long-short-desc} & \abbrstyle{long-short-desc}\\ +\acrstyle{long-sc-short-desc} & \abbrstyle{long-short-sc-desc}\\ +\acrstyle{long-sm-short-desc} & \abbrstyle{long-short-sm-desc}\\ +\acrstyle{long-sp-short-desc} & \abbrstyle{long-short-desc} \newline with +\ttfamily\cs{renewcommand}\{\cs{glsxtrfullsep}\}[1]\{\cs{glsacspace}\{\#1\}\}\\ +\acrstyle{short-long-desc} & \abbrstyle{short-long-desc}\\ +\acrstyle{sc-short-long-desc} & \abbrstyle{short-sc-long-desc}\\ +\acrstyle{sm-short-long-desc} & \abbrstyle{short-sm-long-desc}\\ +\acrstyle{dua} & \abbrstyle{long-noshort}\\ +\acrstyle{dua-desc} & \abbrstyle{long-noshort-desc}\\ +\acrstyle{footnote} & \abbrstyle{short-footnote}\\ +\acrstyle{footnote-sc} & \abbrstyle{short-sc-footnote}\\ +\acrstyle{footnote-sm} & \abbrstyle{short-sm-footnote}\\ +\acrstyle{footnote-desc} & \abbrstyle{short-footnote-desc}\\ +\acrstyle{footnote-sc-desc} & \abbrstyle{short-sc-footnote-desc}\\ +\acrstyle{footnote-sm-desc} & \abbrstyle{short-sm-footnote-desc} +\end{tabular} +\end{table} + +The reason for introducing the new style of abbreviation commands +provided by \styfmt{glossaries-extra} is because the original +acronym commands provided by \styfmt{glossaries} are too restrictive +to work with the internal modifications made by +\styfmt{glossaries-extra}. However, if you really want to restore +the generic acronym function provided +by \styfmt{glossaries} you can use +\begin{definition}[\DescribeMacro\RestoreAcronyms] +\cs{RestoreAcronyms} +\end{definition} +(before any use of \cs{newacronym}). + +\cs{RestoreAcronyms} should not be used in combination with the newer +\styfmt{glossaries-extra} abbreviations. Don't combine old and +new style entries with the same \gloskey{type}. The +original \styfmt{glossaries} acronym mechanism doesn't work well +with the newer \styfmt{glossaries-extra} commands. + +\begin{important} +If you use \cs{RestoreAcronyms}, don't use any of the commands +provided by \styfmt{glossaries-extra} intended for abbreviations +(such as \ics{glsxtrshort} or \ics{glsfmtshort}) with entries +defined via \ics{newacronym} as it will cause unexpected +results. +\end{important} + +In general, there's rarely any need for \cs{RestoreAcronyms}. If you +have a document that uses \ics{newacronymstyle}, then it's best to +either stick with just \styfmt{glossaries} for that document or +define an equivalent abbreviation style with +\ics{newabbreviationstyle}. (See \sectionref{sec:newabbrvstyle} for +further details.) + +\begin{definition}[\DescribeMacro\glsacspace] +\cs{glsacspace}\marg{label} +\end{definition} +The space command \cs{glsacspace} used by the +\acrstyle{long-sp-short} acronym style provided by \styfmt{glossaries} +is modified so that it uses +\begin{definition}[\DescribeMacro\glsacspacemax] +\cs{glsacspacemax} +\end{definition} +instead of the hard-coded 3em. This is a command not a length +and so can be changed using \cs{renewcommand}. + +Any of the new abbreviation styles that use \ics{glsxtrfullsep} +(such as \abbrstyle{long-short}) can easily be changed to use +\cs{glsacspace} with +\begin{verbatim} +\renewcommand*{\glsxtrfullsep}[1]{\glsacspace{#1}} +\end{verbatim} + +The \gls{firstuse} acronym font command +\begin{definition}[\firstacronymfont] +\cs{firstacronymfont}\marg{text} +\end{definition} +is redefined to use the \gls{firstuse} abbreviation font command +\ics{glsfirstabbrvfont}. This will be reset if you use +\cs{RestoreAcronyms}. + +The subsequent use acronym font command +\begin{definition}[\acronymfont] +\cs{acronymfont}\marg{text} +\end{definition} +is redefined to use the subsequent use abbreviation font command +\ics{glsabbrvfont}. This will be reset if you use +\cs{RestoreAcronyms}. + +\section{\styfmt{glossary-bookindex} package} +\label{sec:bookindex} + +As from v1.21, \styfmt{glossaries-extra} has a new supplementary +package \sty{glossary-bookindex} which provides the glossary style +\glostyle{bookindex}. This is very similar to the +\glostyle{mcolindexgroup} style but is designed for indexes, so by +default only the name and location list are displayed. You can +either load this package explicitly and then set the style: +\begin{verbatim} +\usepackage{glossaries-extra} +\usepackage{glossary-bookindex} +\setglossarystyle{bookindex} +\end{verbatim} +or use both the \pkgopt{stylemods} and \sty{style} options: +\begin{verbatim} +\usepackage[stylemods=bookindex,style=bookindex]{glossaries-extra} +\end{verbatim} +The \glostyle{bookindex} style only supports a maximum +hierarchical level of 2 (top-level, level~1 and level~2). It's +primarily designed for use with \gls{bib2gls}. It may be used with +other indexing options, but some features may not be present and +UTF-8 characters may cause a problem with non-Unicode engines in +letter group headings or PDF bookmarks. (\gls{bib2gls} uses numeric +identifies by default to avoid these problems. If numbers show up in +the group headings instead of the appropriate characters, check that +you have used the \pkgopt{record} package option.) + +The number of columns is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexcols] +\cs{glsxtrbookindexcols} +\end{definition} +which defaults to 2. + +This style uses the \env{multicols} environment. If +the command +\begin{definition}[\DescribeMacro\glsxtrbookindexcolspread] +\cs{glsxtrbookindexcolspread} +\end{definition} +isn't empty then it's supplied as the optional argument +following \verb|\begin{multicols}|\marg{n}. You can switch from +\env{multicols} to \env{multicols*} by redefining +\begin{definition}[\DescribeMacro\glsxtrbookindexmulticolsenv] +\cs{glsxtrbookindexmulticolsenv} +\end{definition} +For example +\begin{verbatim} +\renewcommand{\glsxtrbookindexmulticolsenv}{multicols*} +\end{verbatim} + +Each top-level entry is displayed using +\begin{definition}[\DescribeMacro\glsxtrbookindexname] +\cs{glsxtrbookindexname}\marg{label} +\end{definition} +where the entry is identified by \meta{label}. This just +does \cs{glossentryname}\marg{label} by default. +For example, if you want the symbol to be included: +\begin{verbatim} +\renewcommand*{\glsxtrbookindexname}[1]{% + \glossentryname{#1}% + \ifglshassymbol{#1}{\space (\glossentrysymbol{#1})}{}% +} +\end{verbatim} +or if you want the description (if set): +\begin{verbatim} +\renewcommand*{\glsxtrbookindexname}[1]{% + \glossentryname{#1}% + \ifglshasdesc{#1}{\space \glossentrydesc{#1}\glspostdescription}{}% +} +\end{verbatim} +(which picks up the post-description hook). + +Alternatively you can use the \cs{glsxtrpostname\meta{category}} +hook to append information after the name according to the entry's +category. + +Sub-entries are displayed using +\begin{definition}[\DescribeMacro\glsxtrbookindexsubname] +\cs{glsxtrbookindexsubname}\marg{label} +\end{definition} +which just defaults to \cs{glsxtrbookindexname}\marg{label}. + +The separator used before the location list for top-level +entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexprelocation] +\cs{glsxtrbookindexprelocation}\marg{label} +\end{definition} +where \meta{label} is the entry's label. This checks if +the \texttt{location} field has been set. If it has, it +does +\begin{verbatim} +,\glsxtrprelocation +\end{verbatim} +otherwise it just does \cs{glsxtrprelocation} (which defaults +to \cs{space}). If you're not using +\gls{bib2gls}, the \gloskey{location} field won't be set. + +The separator used before the +location list for sub-entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexsubprelocation] +\cs{glsxtrbookindexsubprelocation}\marg{label} +\end{definition} +which defaults to \cs{glsxtrbookindexprelocation}\marg{label}. + +The actual location list is encapsulated with: +\begin{definition}[\DescribeMacro\glsxtrbookindexlocation] +\cs{glsxtrbookindexlocation}\marg{label}\marg{location list} +\end{definition} +for top-level entries and +\begin{definition}[\DescribeMacro\glsxtrbookindexsublocation] +\cs{glsxtrbookindexsublocation}\marg{label}\marg{location list} +\end{definition} +for sub-entries. These both just do \meta{location list} by default. + +The separator used between a top-level parent and child entry is +given by +\begin{definition}[\DescribeMacro\glsxtrbookindexparentchildsep] +\cs{glsxtrbookindexparentchildsep} +\end{definition} +This defaults to \cs{nopagebreak}. + +The separator used between a sub-level parent and child entry is +given by +\begin{definition}[\DescribeMacro\glsxtrbookindexparentsubchildsep] +\cs{glsxtrbookindexparentsubchildsep} +\end{definition} +This defaults to \cs{glsxtrbookindexparentchildsep}. + +The separator between top-level entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexbetween] +\cs{glsxtrbookindexbetween}\marg{label1}\marg{label2} +\end{definition} +This comes after the entry given by \meta{label1}, if the entry +has no children, or after the last descendent otherwise, +so it always comes immediately before the entry given +by \meta{label2} unless the entry occurs at the start of +a group. This does nothing by default. + +The separator between two level~1 entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexsubbetween] +\cs{glsxtrbookindexsubbetween}\marg{label1}\marg{label2} +\end{definition} + +The separator between two level~2 entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexsubsubbetween] +\cs{glsxtrbookindexsubsubbetween}\marg{label1}\marg{label2} +\end{definition} +At the end of each letter group, the following hooks +are done in order: +\begin{definition}[\DescribeMacro\glsxtrbookindexsubsubatendgroup] +\cs{glsxtrbookindexsubsubatendgroup}\marg{sub-sub-label} +\end{definition} +\begin{definition}[\DescribeMacro\glsxtrbookindexsubatendgroup] +\cs{glsxtrbookindexsubatendgroup}\marg{sub-label} +\end{definition} +\begin{definition}[\DescribeMacro\glsxtrbookindexatendgroup] +\cs{glsxtrbookindexatendgroup}\marg{label} +\end{definition} +where \meta{sub-sub-label} is the label of the last +level~2 entry, \meta{sub-label} is the label of the last +level~1 entry and \meta{label} is the label of the last +level~0 entry. + +For example, the resource option \texttt{seealso=omit} +instructs \gls{bib2gls} to omit the \texttt{seealso} cross-reference +from the location list. (The \texttt{see} cross-reference +will still be added unless you also have \texttt{see=omit}.) +The \texttt{seealso} cross-reference can instead be appended after +the child entries using: +\begin{verbatim} +\renewcommand{\glsxtrbookindexatendgroup}[1]{% + \glsxtrifhasfield{seealso}{#1}{\glstreesubitem\glsxtruseseealso{#1}}{}% +} +\renewcommand{\glsxtrbookindexbetween}[2]{% + \glsxtrbookindexatendgroup{#1}% +}% + +\renewcommand{\glsxtrbookindexsubatendgroup}[1]{% + \glsxtrifhasfield{seealso}{#1}{\glstreesubsubitem\glsxtruseseealso{#1}}{}% +} + +\renewcommand{\glsxtrbookindexsubbetween}[2]{% + \glsxtrbookindexsubatendgroup{#1}% +} + +\renewcommand{\glsxtrbookindexsubsubatendgroup}[1]{% + \glsxtrifhasfield{seealso}{#1}% + {\glstreeitem\hspace*{40pt}\glsxtruseseealso{#1}}{}% +} + +\renewcommand{\glsxtrbookindexsubsubbetween}[2]{% + \glsxtrbookindexsubsubatendgroup{#1}% +} +\end{verbatim} +This uses \cs{glstreesubitem} and \cs{glstreesubsubitem} +to indent the cross-reference according to the next level down, +so the cross-reference for a top-level entry is aligned with +the sub-entries, and a level~1 entry has its cross-reference +aligned with sub-sub-entries. In the event that a level~2 +entry has a cross-reference, this is indented a bit further +(but it won't be aligned with any deeper level as the +\glostyle{bookindex} style only supports a maximum of two +sub-levels). + +The \glostyle{bookindex} style uses group headings. (If you +use \gls{bib2gls} remember to invoke it with the \verb|--group| +or \verb|-g| switch.) The heading will use +\begin{definition}[\DescribeMacro\glsxtrbookindexbookmark] +\cs{glsxtrbookindexbookmark}\marg{group title}\marg{name} +\end{definition} +If \cs{pdfbookmark} has been defined, this will +use that command to bookmark the group title. If +\pkgopt[chapter]{section} is set (default if chapters are defined) +then this uses level~1 otherwise it uses level~2. You can +redefine this command if this isn't appropriate. +If \cs{pdfbookmark} hasn't been defined, this command does nothin. + +The group heading is formatted according to +\begin{definition}[\DescribeMacro\glsxtrbookindexformatheader] +\cs{glsxtrbookindexformatheader}\marg{group title} +\end{definition} +which is defined as +\begin{verbatim} +\newcommand*{\glsxtrbookindexformatheader}[1]{% + \par{\centering\glstreegroupheaderfmt{#1}\par}% +} +\end{verbatim} +where \cs{glstreegroupheaderfmt} is provided by the +\sty{glossary-tree} package, which is automatically loaded. +Note that the entry names aren't encapsulated with +\cs{glstreenamefmt}. + +The \sty{glossary-bookindex} package provides some supplementary +commands that aren't used by default, but may be used when +adjusting the style. These commands should only be +used within one of the \cs{print\ldots glossary} commands. +(That is, they should only be used in glossary styles.) +\begin{definition}[\DescribeMacro\glsxtrbookindexmarkentry] +\cs{glsxtrbookindexmarkentry}\marg{label} +\end{definition} +This writes information to the \texttt{.aux} file that +can be read on the next run to obtain the first and last entry on +each page of the glossary. + +You can display the first entry +associated with the current page using: +\begin{definition}[\DescribeMacro\glsxtrbookindexfirstmark] +\cs{glsxtrbookindexfirstmark} +\end{definition} +and the last entry associated with the current page +using: +\begin{definition}[\DescribeMacro\glsxtrbookindexlastmark] +\cs{glsxtrbookindexlastmark} +\end{definition} +These do nothing if there are no entries marked on the current page +(or if the document build isn't up to date). + +The entry is formatted using: +\begin{definition}[\DescribeMacro\glsxtrbookindexfirstmarkfmt] +\cs{glsxtrbookindexfirstmarkfmt}\marg{label} +\end{definition} +for the first instance and +\begin{definition}[\DescribeMacro\glsxtrbookindexlastmarkfmt] +\cs{glsxtrbookindexlastmarkfmt}\marg{label} +\end{definition} +for the last. + +These commands are designed for use in page headers or footers +where the page number is stable. For example, \cs{glsxtrbookindexname} +can be redefined to mark the current entry: +\begin{verbatim} +\renewcommand{\glsxtrbookindexname}[1]{% + \glsxtrbookindexmarkentry{#1}% + \glossentryname{#1}% +} +\end{verbatim} +If you only want to mark the top-level entries, remember +to redefine \cs{glsxtrbookindexsubname} as it defaults +to \cs{glsxtrbookindexname}: +\begin{verbatim} +\renewcommand{\glsxtrbookindexsubname}[1]{% + \glossentryname{#1}% +} +\end{verbatim} + +Then if you're using \sty{fancyhdr} you can set the page style +to show the first and last entry for the current page with: +\begin{verbatim} + \pagestyle{fancy}% + \lhead{\thepage}% + \lfoot{\glsxtrbookindexfirstmark}% + \cfoot{}% + \rfoot{\glsxtrbookindexlastmark}% +\end{verbatim} + +\section{\styfmt{glossary-longextra} package} +\label{sec:longextra} + +As from version 1.37, the \styfmt{glossaries-extra} package comes +with the supplementary package \sty{glossary-longextra} that +provides additional styles, listed below, that use the +\env{longtable} environment. If you know that your glossary won't +span more than a page and you need to use it in a context that's +incompatible with \env{longtable}, you can instead setup these styles +to use \env{tabular} instead. In order to do this you must use +\begin{definition}[\DescribeMacro\GlsLongExtraUseTabulartrue] +\cs{GlsLongExtraUseTabulartrue} +\end{definition} +\emph{before the style is set}. For example: +\begin{verbatim} +\GlsLongExtraUseTabulartrue +\setglossarystyle{long-name-desc} +\end{verbatim} +or +\begin{verbatim} +\GlsLongExtraUseTabulartrue +\printunsrtglossary[style={long-name-desc}] +\end{verbatim} +If you use this setting, you can change the default vertical +alignment with: +\begin{definition}[\DescribeMacro\glslongextraTabularVAlign] +\cs{glslongextraTabularVAlign} +\end{definition} +The default definition is \texttt{c}. + +The column titles are formatted according to: +\begin{definition}[\DescribeMacro\glslongextraHeaderFmt] +\cs{glslongextraHeaderFmt}\marg{text} +\end{definition} +which simply does \cs{textbf}\marg{text} by default. + +The name column has the title given by \ics{entryname} and +the column alignment is given by: +\begin{definition}[\DescribeMacro\glslongextraNameAlign] +\cs{glslongextraNameAlign} +\end{definition} +which expands to \texttt{l} (left) by default. + +The symbol column (where applicable) has the title given by +\ics{symbolname} and the column alignment is given by: +\begin{definition}[\DescribeMacro\glslongextraSymbolAlign] +\cs{glslongextraSymbolAlign} +\end{definition} +which expands to \texttt{c} (centred) by default. + +The location list column (where applicable) has the title given by +\ics{pagelistname} and the column alignment is given by: +\begin{definition}[\DescribeMacro\glslongextraLocationAlign] +\cs{glslongextraLocationAlign} +\end{definition} +which expands to +\begin{verbatim} +>{\raggedright}p{\glspagelistwidth} +\end{verbatim} +by default. (Ragged-right paragraph, \ics{glspagelistwidth} is +defined in \sty{glossary-long}, which is automatically loaded.) + +The description column has the title given by \ics{descriptionname} +and the column alignment is given by: +\begin{definition}[\DescribeMacro\glslongextraDescAlign] +\cs{glslongextraDescAlign} +\end{definition} +which expands to +\begin{verbatim} +>{\raggedright}p{\glsdescwidth} +\end{verbatim} +by default. (Ragged-right paragraph, \ics{glsdescwidth} is +defined in \sty{glossary-long}, which is automatically loaded.) + +Unlike the long styles provided by the base \styfmt{glossaries} +package, these new styles try to determine the value of +\cs{glsdescwidth} at the start of the glossary according to the +number of columns provided by the style. The calculations are +performed by the following commands: +\begin{definition}[\DescribeMacro\glslongextraSetDescWidth] +\cs{glslongextraSetDescWidth} +\end{definition} +This is used by the styles that have a name and description +column. The value of \cs{glsdescwidth} is computed as: +\[ + \cs{glsdescwidth} = \cs{linewidth} - 4\cs{tabcolsep} - W +\] +where $W$ is a guess at the width of the name column. This is first +set to the width of the name column header: +\begin{alltt} +\cs{settowidth}\marg{width}\{\cs{glslongextraHeaderFmt}\cs{entryname}\} +\end{alltt} +If any names in that column are larger than this, then you need +to specify the widest name using: +\begin{definition}[\DescribeMacro\glslongextraSetWidest] +\cs{glslongextraSetWidest}\marg{widest name} +\end{definition} +or +\begin{definition}[\DescribeMacro\glslongextraUpdateWidest] +\cs{glslongextraUpdateWidest}\marg{text} +\end{definition} +These work like the analogous commands \cs{glssetwidest} and +\cs{glsupdatewidest} provided with the \glostyle{alttree} style, but +in this case there's no hierarchy. The default widest name +is obtained from the \glostyle{alttree} top-level name if set, +otherwise it's empty, so you can use \gls{bib2gls}['s] +\texttt{set-widest} option. If you have the entry counter enabled, +you will need to include this with the name for the extra material to +be taken into account. + +The name isn't shown for child entries by default, but if +you change this and you want to use \gls{bib2gls}['s] +\texttt{set-widest} option (for \gls{bib2gls} v1.8+) then you need to +redefine: +\begin{definition}[\DescribeMacro\glslongextraUpdateWidestChild] +\cs{glslongextraUpdateWidestChild}\marg{level}\marg{text} +\end{definition} +This does nothing by default, but if you are including the child +names then you need to redefine this command: +\begin{verbatim} +\renewcommand{\glslongextraUpdateWidestChild}[2]{% + \glslongextraUpdateWidest{#2}% +} +\end{verbatim} + +If you prefer to set an explicit width for the description +column then you need to redefine \cs{glslongextraSetDescWidth}. For +example: +\begin{verbatim} +\renewcommand{\glslongextraSetDescWidth}{% + \setlength{\glsdescwidth}{0.6\linewidth}% +} +\end{verbatim} + +The styles that have a name, symbol and description, +\cs{glsdescwidth} is set with: +\begin{definition}[\DescribeMacro\glslongextraSymSetDescWidth] +\cs{glslongextraSymSetDescWidth} +\end{definition} +This first uses \cs{glslongextraSetDescWidth} and then subtracts +2\cs{tabcolsep} and the width of the symbol column header from +\cs{glsdescwidth}. This assumes that the symbol column header +is larger than any of the symbols. If this isn't appropriate +then you can redefine this command. For example: +\begin{verbatim} +\renewcommand{\glslongextraSymSetDescWidth}{% + \glslongextraSetDescWidth + \addtolength{\glsdescwidth}{-3cm}% +} +\end{verbatim} +or +\begin{verbatim} +\renewcommand{\glslongextraSymSetDescWidth}{% + \setlength{\glsdescwidth}{.5\linewidth}% +} +\end{verbatim} + +For the styles that have a name, description and location column, +\cs{glsdescwidth} is set using: +\begin{definition}[\DescribeMacro\glslongextraLocSetDescWidth] +\cs{glslongextraLocSetDescWidth} +\end{definition} +This uses \cs{glslongextraSetDescWidth} and then subtracts +2\cs{tabcolsep} and \cs{glspagelistwidth} from \cs{glsdescwidth}. +You can redefine this command to set both \cs{glsdescwidth} and +\cs{glspagelistwidth} if appropriate. + +For the styles that have a name, description, symbol and location +column, \cs{glsdescwidth} is set using: +\begin{definition}[\DescribeMacro\glslongextraSymLocSetDescWidth] +\cs{glslongextraSymLocSetDescWidth} +\end{definition} +This uses \cs{glslongextraSymSetDescWidth} and then subtracts +2\cs{tabcolsep} and \cs{glspagelistwidth} from +\cs{glsdescwidth}. Again, you can redefine this command +to explicitly set both lengths. + +In all cases, the top-level name is formatted according to: +\begin{definition}[\DescribeMacro\glslongextraNameFmt] +\cs{glslongextraNameFmt}\marg{label} +\end{definition} +This does +\begin{alltt} +\cs{glsentryitem}\marg{label}\cs{glstarget}\marg{label}\{\cs{glossentryname}\marg{label}\} +\end{alltt} +which includes the entry counter (if enabled), the target and the post-name link. + +The top-level description is formatted according to: +\begin{definition}[\DescribeMacro\glslongextraDescFmt] +\cs{glslongextraDescFmt}\marg{label} +\end{definition} +This does \cs{glossentrydesc}\marg{label} followed by the +post-description hook. + +The styles that have a symbol column format the symbol using: +\begin{definition}[\DescribeMacro\glslongextraSymbolFmt] +\cs{glslongextraSymbolFmt}\marg{label} +\end{definition} +This just does \cs{glossentrysymbol}\marg{label}. + +The styles that have a location list column format the list using: +\begin{definition}[\DescribeMacro\glslongextraLocationFmt] +\cs{glslongextraLocationFmt}\marg{label}\marg{locations} +\end{definition} +This just does \meta{locations} and ignores the label. + +The child entries have their name formatted according to: +\begin{definition}[\DescribeMacro\glslongextraSubNameFmt] +\cs{glslongextraSubNameFmt}\marg{level}\marg{label} +\end{definition} +where \meta{level} is the hierarchical level. This defaults to: +\begin{alltt} +\cs{glssubentryitem}\marg{label}\cs{glstarget}\marg{label}\{\cs{strut}\} +\end{alltt} +This includes the sub-entry counter (if enabled) and the target +but doesn't show the name. The child description is formatted according to: +\begin{definition}[\DescribeMacro\glslongextraSubDescFmt] +\cs{glslongextraSubDescFmt}\marg{level}\marg{label} +\end{definition} +which defaults to just \cs{glslongextraDescFmt}\marg{label} + +The child symbol is formatted (where appropriate) according to: +\begin{definition}[\DescribeMacro\glslongextraSubSymbolFmt] +\cs{glslongextraSubSymbolFmt}\marg{level}\marg{label} +\end{definition} +This just does \cs{glslongextraSymbolFmt}\marg{label} by default. + +The styles that have a location list column format the list for +child entries using: +\begin{definition}[\DescribeMacro\glslongextraLocationFmt] +\cs{glslongextraSubLocationFmt}\meta{level}\marg{label}\marg{locations} +\end{definition} +This just does \meta{locations} and ignores the level and label. + +The letter group headings are formatted according to: +\begin{definition}[\DescribeMacro\glslongextraGroupHeading] +\cs{glslongextraGroupHeading}\marg{n}\marg{label} +\end{definition} +which does nothing by default. The first argument \meta{n} is the +number of columns in the table. The second argument \meta{label} +is the group label (not the title, although they may happen +to be the same). + +This can be redefined to show the group heading. For example: +\begin{verbatim} +\renewcommand*{\glslongextraGroupHeading}[2]{% + \glsxtrgetgrouptitle{#2}{\thisgrptitle}% + \glslongextraHeaderFmt{\thisgrptitle}% + \tabularnewline + \noalign{\vskip\normalbaselineskip}% +} +\end{verbatim} +This ignores the first argument and just puts the group +title in the first column formatted according to +\cs{glslongextraHeaderFmt} (to match the column header). + +Remember that you can also adjust the styles through category +attributes. The name column's title is given by +\cs{entryname}, the description column's title is given by +\cs{descriptionname} and (where present) the symbol column's +title is given by \cs{symbolname}, as for the other long styles +that have headers. + +\begin{description} +\item{\glostyle{long-name-desc}} This is like the +\glostyle{longragged-booktabs} style but doesn't show the location +list (regardless of the \pkgopt{nonumberlist} option). The name is +shown in the first column and the description in the second. + +The symbol is not displayed. The header +row is produced with: +\begin{definition}[\DescribeMacro\glslongextraNameDescHeader] +\cs{glslongextraNameDescHeader} +\end{definition} +This essentially uses the same code as for \glostyle{longragged-booktabs} +but makes it easier to adjust the header without having to define a +new style. This is defined as: +\begin{verbatim} +\glslongextraNameDescTabularHeader\endhead +\glslongextraNameDescTabularFooter\endfoot +\end{verbatim} +where: +\begin{definition}[\DescribeMacro\glslongextraNameDescTabularHeader] +\cs{glslongextraNameDescTabularHeader} +\end{definition} +sets up the header and +\begin{definition}[\DescribeMacro\glslongextraNameDescTabularFooter] +\cs{glslongextraNameDescTabularFooter} +\end{definition} +sets up the footer. If you have setup the \env{tabular} version +of this style then the above two commands are used at the +start and end of the \env{tabular} environment (and +\cs{glslongextraNameDescHeader} isn't used). + +For example, to simply remove the header and footer (for the default +\env{longtable} version of the style): +\begin{verbatim} +\renewcommand{\glslongextraNameDescHeader}{} +\end{verbatim} +Or to change the name alignment to centred: +\begin{verbatim} +\renewcommand{\glslongextraNameAlign}{c} +\end{verbatim} + +\item{\glostyle{long-name-desc-loc}} This is like the +\glostyle{long-name-desc} style but has a third column for the +location list. The \env{longtable} header is given by: +\begin{definition}[\DescribeMacro\glslongextraNameDescLocationHeader] +\cs{glslongextraNameDescLocationHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameDescLocationTabularHeader] +\cs{glslongextraNameDescLocationTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraNameDescLocationTabularFooter] +\cs{glslongextraNameDescLocationTabularFooter} +\end{definition} + +\item{\glostyle{long-desc-name}} This is like the +\glostyle{long-name-desc} style but swaps the columns. Note that +if the entry counter is displayed it will appear at the start +of the second column by default. The \env{longtable} header is formatted according +to: +\begin{definition}[\DescribeMacro\glslongextraDescNameHeader] +\cs{glslongextraDescNameHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraDescNameTabularHeader] +\cs{glslongextraDescNameTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraDescNameTabularFooter] +\cs{glslongextraDescNameTabularFooter} +\end{definition} + +\item{\glostyle{long-loc-desc-name}} This has three columns +containing the location list, description and name. The +\env{longtable} header +is formatted according to: +\begin{definition}[\DescribeMacro\glslongextraLocationDescNameHeader] +\cs{glslongextraLocationDescNameHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraLocationDescNameTabularHeader] +\cs{glslongextraLocationDescNameTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraLocationDescNameTabularFooter] +\cs{glslongextraLocationDescNameTabularFooter} +\end{definition} + +\item{\glostyle{long-name-desc-sym}} This is has three columns, with +the name in the first, the description in the second and the symbol +in the third. + +The \env{longtable} header row is produced with: +\begin{definition}[\DescribeMacro\glslongextraNameDescSymHeader] +\cs{glslongextraNameDescSymHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameDescSymTabularHeader] +\cs{glslongextraNameDescSymTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraNameDescSymTabularFooter] +\cs{glslongextraNameDescSymTabularFooter} +\end{definition} + +\item{\glostyle{long-name-desc-sym-loc}} This is has four columns, with +the name in the first, the description in the second, the symbol +in the third and the location list in the fourth. + +The \env{longtable} header row is produced with: +\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationHeader] +\cs{glslongextraNameDescSymLocationHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationTabularHeader] +\cs{glslongextraNameDescSymLocationTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationTabularFooter] +\cs{glslongextraNameDescSymLocationTabularFooter} +\end{definition} + +\item{\glostyle{long-name-sym-desc}} This is like the +\glostyle{long-name-desc-sym} but the second and third column are +swapped. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraNameSymDescHeader] +\cs{glslongextraNameSymDescHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameSymDescTabularHeader] +\cs{glslongextraNameSymDescTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraNameSymDescTabularFooter] +\cs{glslongextraNameSymDescTabularFooter} +\end{definition} + +\item{\glostyle{long-name-sym-desc-loc}} This is like the +\glostyle{long-name-desc-sym-loc} but the second and third column are +swapped. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationHeader] +\cs{glslongextraNameSymDescLocationHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationTabularHeader] +\cs{glslongextraNameSymDescLocationTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationTabularFooter] +\cs{glslongextraNameSymDescLocationTabularFooter} +\end{definition} + +\item{\glostyle{long-sym-desc-name}} This has the symbol in the +first column, the description in the second and the name in the +third. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraSymDescNameHeader] +\cs{glslongextraSymDescNameHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraSymDescNameTabularHeader] +\cs{glslongextraSymDescNameTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraSymDescNameTabularFooter] +\cs{glslongextraSymDescNameTabularFooter} +\end{definition} + +\item{\glostyle{long-loc-sym-desc-name}} This has the location list +in the first column, symbol in the +second column, the description in the third and the name in the +fourth. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameHeader] +\cs{glslongextraLocationSymDescNameHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameTabularHeader] +\cs{glslongextraLocationSymDescNameTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameTabularFooter] +\cs{glslongextraLocationSymDescNameTabularFooter} +\end{definition} + +\item{\glostyle{long-desc-sym-name}} This has the description in the +first column, the symbol in the second and the name in the +third. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraDescSymNameHeader] +\cs{glslongextraDescSymNameHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraDescSymNameTabularHeader] +\cs{glslongextraDescSymNameTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraDescSymNameTabularFooter] +\cs{glslongextraDescSymNameTabularFooter} +\end{definition} + +\item{\glostyle{long-loc-desc-sym-name}} This has the location list +in the first column, the description in the +second column, the symbol in the third and the name in the +fourth. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameHeader] +\cs{glslongextraLocationDescSymNameHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameTabularHeader] +\cs{glslongextraLocationDescSymNameTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameTabularFooter] +\cs{glslongextraLocationDescSymNameTabularFooter} +\end{definition} + +\end{description} + +\section{\styfmt{glossary-topic} package} +\label{sec:topic} + +As from version 1.40, the \styfmt{glossaries-extra} package comes +with the supplementary package \sty{glossary-topic} that +provides glossary styles designed for hierarchical glossaries +where the top-level entries are topic titles. This package +automatically loads the \sty{multicols} package. If the +\sty{glossary-tree} package is also loaded then commands like +\cs{glssetwidest} can be used on these styles in much the same way +as for the \glostyle{alttree} style. If a widest value isn't set +then these styles behave more like the \glostyle{tree} style. +\begin{description} +\item[\glostyle{topic}] This style is similar to the \glostyle{tree} +style but the indentation doesn't start until the second +sub-item level. The top-level entries have the name displayed +in a larger font with the description following in a new paragraph. +This style doesn't support the \pkgopt{nogroupskip} setting. + +\item[\glostyle{topicmcols}] This style is like the \glostyle{topic} +style but the sub-entries are placed inside a \env{multicols} +environment. The environment name is supplied in the value of +the command: +\begin{definition}[\DescribeMacro\glstopicColsEnv] +\cs{glstopicColsEnv} +\end{definition} +You can change this to the starred form. For example: +\begin{verbatim} +\renewcommand{\glstopicColsEnv}{multicols*} +\end{verbatim} +The number of columns is given by the command: +\begin{definition}[\DescribeMacro\glstopicCols] +\cs{glstopicCols} +\end{definition} +The default value is 2. +\end{description} +Both styles use the following commands. +\begin{definition}[\DescribeMacro\glstopicParIndent] +\cs{glstopicParIndent} +\end{definition} +This command is a length that's used for the paragraph indentation +in any multi-paragraph description for top-level entries, but not +for the first paragraph (at the start of the description) which +isn't indented. + +\begin{definition}[\DescribeMacro\glstopicSubIndent] +\cs{glstopicSubIndent} +\end{definition} +This command is a length that's used to calculate the hanging +indentation for sub-entries. The level~1 sub-entries don't indent +the name. Level~$n$ sub-entries have the name indented by +$(n-1)\times$\cs{glstopicSubIndent}. The hanging indent depends +on whether or not a widest name has been set for the level. + +\begin{definition}[\DescribeMacro\glstopicInit] +\cs{glstopicInit} +\end{definition} +Hook used at the start of the glossary. Does nothing by default. + +Although the styles don't support letter groups by default, if you +have many topics (top-level entries) and you feel that it would help +the reader to divide them up into headed letter groups, you can +redefine: +\begin{definition}[\DescribeMacro\glstopicGroupHeading] +\cs{glstopicGroupHeading}\marg{group label} +\end{definition} +This does nothing by default. If you want to redefine it, you can +fetch the title corresponding to the group label with +\cs{glsxtrgetgrouptitle}. For example: +\begin{verbatim} +\renewcommand*{\glstopicGroupHeading}[1]{% + \glsxtrgetgrouptitle{#1}{\thisgrptitle}% + \section*{\thisgrptitle}% +} +\end{verbatim} +Remember that if you use \gls{bib2gls}, you will need the +\verb|--group| (or \verb|-g|) switch to support this. + +\begin{definition}[\DescribeMacro\glstopicItem] +\cs{glstopicItem}\marg{label}\marg{location list} +\end{definition} +Used to format the name, symbol, description and location list +for the top-level entries. This starts with a paragraph break +followed by: +\begin{definition}[\DescribeMacro\glstopicPreSkip] +\cs{glstopicPreSkip} +\end{definition} +which defaults to \cs{medskip}. There is then a hook: +\begin{definition}[\DescribeMacro\glstopicMarker] +\cs{glstopicMarker}\marg{label} +\end{definition} +which does nothing by default, but may be redefined. For example, +to add a line to the table of contents. +The name and symbol are set in the +form of a title using: +\begin{definition}[\DescribeMacro\glstopicTitle] +\cs{glstopicTitle}\marg{label} +\end{definition} +This uses \cs{Glossentryname} which converts the first letter to +upper case. If there's a symbol, this is added in parentheses. +Both name and symbol (if present) are encapsulated by +\begin{definition}[\DescribeMacro\glstopicTitleFont] +\cs{glstopicTitleFont}\marg{text} +\end{definition} +This uses a bold, large font by default. + +If the entry has the description key set (tested with +\cs{ifglshasdesc}) then a paragraph break is inserted followed by: +\begin{definition}[\DescribeMacro\glstopicMidSkip] +\cs{glstopicMidSkip} +\end{definition} +which defaults to \cs{smallskip}. This is followed by the +description which is formatted according to: +\begin{definition}[\DescribeMacro\glstopicDesc] +\cs{glstopicDesc}\marg{label} +\end{definition} +This just does \cs{Glossentrydesc}\marg{label} followed +by the post-description hook. + +A paragraph break followed by: +\begin{definition}[\DescribeMacro\glstopicPostSkip] +\cs{glstopicPostSkip} +\end{definition} +comes next regardless of whether or not the description was +displayed. This defaults to \cs{smallskip}. This is then followed +by: +\begin{definition}[\DescribeMacro\glstopicLoc] +\cs{glstopicLoc}\marg{label}\marg{location list} +\end{definition} +which may be used to display the location list, but does nothing by +default. + +The sub-entries first set up the paragraph and hanging indentations +using: +\begin{definition}[\DescribeMacro\glstopicAssignSubIndent] +\cs{glstopicAssignSubIndent}\marg{level} +\end{definition} +This uses: +\begin{definition}[\DescribeMacro\glstopicAssignWidest] +\cs{glstopicAssignWidest}\marg{level} +\end{definition} +to determine if a widest name has been set for the given level. + +The sub-entry has its information displayed using: +\begin{definition}[\DescribeMacro\glstopicSubItem] +\cs{glstopicSubItem}\marg{level}\marg{label}\marg{location} +\end{definition} +This encapsulates the name with: +\begin{definition}[\DescribeMacro\glstopicSubNameFont] +\cs{glstopicSubNameFont}\marg{text} +\end{definition} +By default this just uses \cs{textbf}. This is followed by: +\begin{definition}[\DescribeMacro\glstopicSubItemSep] +\cs{glstopicSubItemSep} +\end{definition} +which defaults to \cs{quad}. The name and separator are +passed in the \meta{text} argument of: +\begin{definition}[\DescribeMacro\glstopicSubItemBox] +\cs{glstopicSubItemBox}\marg{level}\marg{text} +\end{definition} +If a widest name was set for the given level, this will +put \meta{text} inside a box of that width otherwise it just does +\meta{text}. + +This is followed by the symbol in parentheses if set. Then, if the +description is set, the description and post-description hook are +displayed followed by: +\begin{definition}[\DescribeMacro\glstopicSubPreLocSep] +\cs{glstopicSubPreLocSep} +\end{definition} +(This command isn't used if the description isn't set.) + +Finally the location list is displayed using: +\begin{definition}[\DescribeMacro\glstopicSubLoc] +\cs{glstopicSubLoc}\marg{label}\marg{location} +\end{definition} +which just does \meta{location} by default. + +\section{Glossary Style Modifications} +\label{sec:glosstylemods} + +The \sty{glossaries-extra-stylemods} package (more conveniently +loaded through the \styfmt{glossaries-extra} +\pkgopt{stylemods} option) modifies some of the predefined +styles that are provided with the \styfmt{glossaries} package. +These modifications are described in more detail in +\sectionref{sec:stylemods}. + +The \sty{glossaries} package tries to determine the group +title from its label by first checking if +\cs{}\meta{label}\texttt{groupname} exists. If it doesn't exist, +then the title is assumed to be the same as the label. +For example, when typesetting the \qt{A} letter group, +\sty{glossaries} first checks if \cs{Agroupname} exists. +This could potentially cause conflict with another package +that may have some other meaning for \cs{Agroupname}, so +\sty{glossaries-extra} first checks for the existence +of the internal command \cs{glsxtr@grouptitle@}\meta{label} +which shouldn't clash with another package. You can set the +group title using +\begin{definition}[\DescribeMacro\glsxtrsetgrouptitle] +\cs{glsxtrsetgrouptitle}\marg{label}\marg{title} +\end{definition} +For example: +\begin{verbatim} +\glsxtrsetgrouptitle{A}{A (a)} +\end{verbatim} +This uses a global assignment. If you need to scope the change +you can use +\begin{definition}[\DescribeMacro\glsxtrlocalsetgrouptitle] +\cs{glsxtrlocalsetgrouptitle}\marg{label}\marg{title} +\end{definition} + +\subsection{Style Hooks} +\label{sec:stylehooks} + +The commands \ics{glossentryname} and \ics{glossentrydesc} are +modified to take into account the \catattr{glossname}, +\catattr{glossdesc} and \catattr{glossdescfont} attributes (see \sectionref{sec:categories}). +This means you can make simple case-changing modifications to +the name and description without defining a new glossary style. + +If you want to adapt a style to use another field instead +of \gloskey{name}, you can use +\begin{definition}[\DescribeMacro\glossentrynameother] +\cs{glossentrynameother}\marg{label}\marg{field} +\end{definition} +This behaves just like \cs{glossentryname} (that is, it obeys +\catattr{glossname}, \catattr{glossnamefont} or \cs{glsnamefont} and uses the post-name +hook) but it uses the given \meta{field} instead of \gloskey{name}. +The \meta{field} argument must be the internal field name +(for example \texttt{desc} rather than \texttt{description}). +See the key to field mappings table in the \styfmt{glossaries} +user manual. + +There is a hook after \ics{glossentryname} and +\ics{Glossentryname}: +\begin{definition}[\DescribeMacro\glsxtrpostnamehook] +\cs{glsxtrpostnamehook}\marg{label} +\end{definition} +By default this checks the \catattr{indexname} attribute. +If the attribute exists for the category to which the label belongs, +then the name is automatically indexed using +\begin{definition} +\ics{glsxtrdoautoindexname}\marg{label}\texttt{\{indexname\}} +\end{definition} +See \sectionref{sec:autoindex} for further details. + +\begin{sloppypar} +As from version 1.04, the post-name hook \cs{glsxtrpostnamehook} +will also use \cs{glsxtrpostname}\meta{category} if it exists. +You can use \ics{glscurrententrylabel} to obtain the entry label +with the definition of this command. For example, suppose you are +using a glossary style the doesn't display the symbol, you can +insert the symbol after the name for a particular category, say, +the \qt{symbol} category: +\end{sloppypar} +\begin{verbatim} +\newcommand*{\glsxtrpostnamesymbol}{\space + (\glsentrysymbol{\glscurrententrylabel})} +\end{verbatim} +For convenience, as from v1.31, you can use +\begin{definition}[\DescribeMacro\glsdefpostname] +\cs{glsdefpostname}\marg{category}\marg{definition} +\end{definition} +This is simply a shortcut for: +\begin{alltt} +\cs{csdef}\{glsxtrpostname\meta{category}\}\marg{definition} +\end{alltt} +Note that it doesn't check if the command has already been defined. + +As from version 1.25, the post-name hook also does +\begin{definition}[\DescribeMacro\glsextrapostnamehook] +\cs{glsextrapostnamehook}\marg{label} +\end{definition} +(before \cs{glsxtrpostname}\meta{category}) +to allow for additional non-category related code. This does nothing +by default. + +The post-description code used within the glossary is modified so +that it also does +\begin{definition}[\DescribeMacro\glsxtrpostdescription] +\cs{glsxtrpostdescription} +\end{definition} +This occurs before the original \cs{glspostdescription}, so if the +\pkgopt[false]{nopostdot} option is used, it will be inserted before +the terminating full stop. + +This new command will do \cs{glsxtrpostdesc\meta{category}} +if it exists, where \meta{category} is the category label associated +with the current entry. For example \cs{glsxtrpostdescgeneral} +for entries with the category set to \category{general} +or \cs{glsxtrpostdescacronym} for entries with the category set to +\category{acronym}. +For convenience, as from v1.31, you can use +\begin{definition}[\DescribeMacro\glsdefpostdesc] +\cs{glsdefpostdesc}\marg{category}\marg{definition} +\end{definition} +This is simply a shortcut for: +\begin{alltt} +\cs{csdef}\{glsxtrpostdesc\meta{category}\}\marg{definition} +\end{alltt} +Note that it doesn't check if the command has already been defined. + +Since both \cs{glossentry} and \cs{subglossentry} set +\begin{definition}[\DescribeMacro\glscurrententrylabel] +\cs{glscurrententrylabel} +\end{definition} +to the label for the current entry, you can use this within the +definition of these post-description hooks if you need to reference +the label. + +For example, suppose you want to insert the plural form in brackets +after the description in the glossary, but only for entries in the +\category{general} category, then you could do: +\begin{verbatim} +\renewcommand{\glsxtrpostdescgeneral}{\space + (plural: \glsentryplural{\glscurrententrylabel})} +\end{verbatim} +This means you don't have to define a custom glossary style, which +you may find more complicated. (It also allows more flexibility if +you decide to change the underlying glossary style.) + +\begin{important} +This feature can't be used for glossary styles that ignore +\cs{glspostdescription} or if you redefine +\cs{glspostdescription} without including \cs{glsxtrpostdescription}. +(For example, if you redefine \cs{glspostdescription} to do +nothing instead of using the \pkgopt{nopostdot} option to suppress +the terminating full stop.) See \sectionref{sec:stylemods} to patch +the predefined styles provided by \styfmt{glossaries} that are missing +\cs{glspostdescription}. +\end{important} + +\subsection{Number List} +\label{sec:glosstylenumlist} + +The \gls{numberlist} is now placed inside the argument of +\begin{definition}[\DescribeMacro\GlsXtrFormatLocationList] +\cs{GlsXtrFormatLocationList}\marg{number list} +\end{definition} +This is internally used by \cs{glossaryentrynumbers}. The +\pkgopt{nonumberlist} option redefines \cs{glossaryentrynumbers} so that it +doesn't display the \gls{numberlist}, but it still saves the +\gls{numberlist} in case it's required. + +\begin{important} +If you want to suppress the \gls{numberlist} always use the +\pkgopt{nonumberlist} option instead of redefining +\cs{glossaryentrynumbers} to do nothing. +\end{important} + +If you want to, for example, change the font for the entire +\gls{numberlist} then redefine \cs{GlsXtrFormatLocationList} as +appropriate. Don't modify \cs{glossaryentrynumbers}. + +Sometimes users like to insert \qt{page} or \qt{pages} in front of +the \gls{numberlist}. This is quite fiddly to do with the base +\styfmt{glossaries} package, but \styfmt{glossaries-extra} +provides a way of doing this. First you need to enable this +option and specify the text to display using: +\begin{definition}[\DescribeMacro\GlsXtrEnablePreLocationTag] +\cs{GlsXtrEnablePreLocationTag}\marg{page}\marg{pages} +\end{definition} +where \meta{page} is the text to display if the \gls{numberlist} only +contains a single location and \meta{pages} is the text to display +otherwise. For example: +\begin{verbatim} +\GlsXtrEnablePreLocationTag{Page: }{Pages: } +\end{verbatim} +An extra run is required when using this command. + +\begin{important} +Use \texttt{glsignore} not \texttt{@gobble} as the format if you +want to suppress the page number (and only index the entry once). +\end{important} + +See the accompanying sample file \texttt{sample-pages.tex}. + +Note that \gls{bib2gls} can be instructed to insert +a prefix at the start of non-empty location lists, which +can be used as an alternative to \cs{GlsXtrEnablePreLocationTag}. + +\subsection{The \styfmt{glossaries-extra-stylemods} Package} +\label{sec:stylemods} + +As from v1.02, \styfmt{glossaries-extra} now includes the package +\sty{glossaries-extra-stylemods} that will redefine the predefined +styles to include the post-description hook (for those that are +missing it). You will need to make sure the styles have already +been defined before loading \styfmt{glossaries-extra}. For example: +\begin{verbatim} +\usepackage{glossaries-extra} +\usepackage{glossary-longragged} +\usepackage{glossaries-extra-stylemods} +\end{verbatim} +Alternatively you can load +\texttt{glossary-}\meta{name}\texttt{.sty} at the same time by +passing \meta{name} as a package option to +\sty{glossaries-extra-stylemods}. For example: +\begin{verbatim} +\usepackage{glossaries-extra} +\usepackage[longragged]{glossaries-extra-stylemods} +\end{verbatim} +Another option is to use the \pkgopt{stylemods} key when you +load \styfmt{glossaries-extra}. You can omit a value if you only want to use +the predefined styles that are automatically loaded by +\styfmt{glossaries} (for example, the \glostyle{long3col} style): +\begin{verbatim} +\usepackage[style=long3col,stylemods]{glossaries-extra} +\end{verbatim} +Or the value of \pkgopt{stylemods} may be a comma-separated list +of the style package identifiers. For example: +\begin{verbatim} +\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra} +\end{verbatim} +Remember to group the value if it contains any commas: +\begin{verbatim} +\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra} +\end{verbatim} + +Note that the \glostyle{inline} style is dealt with slightly +differently. The original definition provided by the +\sty{glossary-inline} package uses \cs{glspostdescription} at the +end of the glossary (not after each entry description) within the +definition of \cs{glspostinline}. The style modification changes +this so that \cs{glspostinline} just does a full stop followed by +space factor adjustment, and the description +\cs{glsinlinedescformat} and sub-entry description formats +\cs{glsinlinesubdescformat} are redefined to include +\cs{glsxtrpostdescription} (not \cs{glspostdescription}). This means +that the modified \glostyle{inline} style isn't affected by the +\pkgopt{nopostdot} option, but the post-description category hook +can still be used. + +The \env{tabular}-like styles, such as \glostyle{long} are +adjusted so that the \ics{ifglsnogroupskip} conditional (set with +\pkgopt{nogroupskip}) is moved outside of the definition of +\cs{glsgroupskip} to avoid problems that cause an \qt{Incomplete +\cs{iftrue}} error with \cs{printunsrtglossary} and +\cs{printnoidxglossary}. This means that if you want to change this +conditional using \cs{setupglossaries} or using the +\gloskey[printglossary]{nogroupskip} option in \cs{printglossary}, +\cs{printnoidxglossary} or \cs{printunsrtglossary}, you must also +reset the glossary style. + +As from version 1.21, the hard-coded \cs{space} before the +\gls{numberlist} in many of the predefined styles is replaced +with +\begin{definition}[\DescribeMacro\glsxtrprelocation] +\cs{glsxtrprelocation} +\end{definition} +This just defaults to \cs{space} but may be redefined as required. +For example: +\begin{verbatim} +\renewcommand{\glsxtrprelocation}{\dotfill} +\end{verbatim} + +The \glostyle{list} styles use +\begin{definition}[\DescribeMacro\glslistprelocation] +\cs{glslistprelocation} +\end{definition} +(which defaults to \cs{glsxtrprelocation}) for top-level items and +\begin{definition}[\DescribeMacro\glslistchildprelocation] +\cs{glslistchildprelocation} +\end{definition} +(which defaults to \cs{glslistprelocation}) for child items. + +As from v1.31, the description (including the post-description hook) +is governed by: +\begin{definition}[\DescribeMacro\glslistdesc] +\cs{glslistdesc}\marg{label} +\end{definition} +for the \glostyle{list} and \glostyle{altlist} styles (but not the +\glostyle{listdotted} variations). + +For just the \glostyle{list} style and its letter group variations +(not the \glostyle{altlist} or \glostyle{listdotted} variations) the +\gls{numberlist} for child entries is followed by +\begin{definition}[\DescribeMacro\glslistchildpostlocation] +\cs{glslistchildpostlocation} +\end{definition} +which defaults to a full stop. + +The default value of \ics{glslistdottedwidth} is changed so that +it's set at the start of the document (if it hasn't been changed in +the preamble). This should take into account situations where +\cs{hsize} isn't set until the start of the document. + +The separator between groups (if not \pkgopt{nogroupskip}) is now +given by: +\begin{definition}[\DescribeMacro\glslistgroupskip] +\cs{glslistgroupskip} +\end{definition} +This defaults to \cs{indexspace} with penalties to deter page +breaks. +This command isn't used if \pkgopt{nogroupskip} is set. + +The \sty{glossary-tree} package introduced two new commands in +\sty{glossaries} version 4.22, \ics{glstreegroupheaderfmt} +and \ics{glstreenavigationfmt}, which are used to format +the letter group headings and the navigation elements for the +appropriate styles. These two new commands are defined in terms of +\ics{glstreenamefmt} since that was the command originally used +for the group headings and navigation. This now allows these +different elements to be defined independently, but the most common +redefinition is for \cs{glstreenamefmt} to remove the bold in the +name. If the bold is still required for the group heading and navigation +elements, then both other commands also need redefining. To simplify +matters, if \cs{glstreenamefmt} has been defined, as from v1.31 +\sty{glossaries-extra-stylemods} defines: +\begin{definition}[\DescribeMacro\glstreedefaultnamefmt] +\cs{glstreedefaultnamefmt}\marg{text} +\end{definition} +which simply does \cs{textbf}\marg{text} and redefines +\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and +\cs{glstreenavigationfmt} all in terms of +\cs{glstreedefaultnamefmt}. This means that if you want to change +all three to use a particular style you only need to redefine +\cs{glstreedefaultnamefmt}, but if you only want to redefine +\cs{glstreenamefmt} without affecting the other two commands, then +you now can. + +The separator between groups (if not \pkgopt{nogroupskip}) is now +given by: +\begin{definition}[\DescribeMacro\glstreegroupskip] +\cs{glstreegroupskip} +\end{definition} +This defaults to \cs{indexspace} with penalties to deter page +breaks. +This command isn't used if \pkgopt{nogroupskip} is set (except for +the styles that display the group titles). + +The styles that display the group titles now use: +\begin{definition}[\DescribeMacro\glstreePreHeader] +\cs{glstreePreHeader}\marg{label}\marg{title} +\end{definition} +where \meta{label} is the group label and \meta{title} is the group +title. This does nothing by default +and is inserted before the group title. You can redefine it to add +the group title to the PDF bookmarks. For example, if the +glossary title uses \cs{chapter} then: +\begin{verbatim} +\renewcommand{\glstreePreHeader}[2]{% + \pdfbookmark[1]{#2}{\currentglossary.#1}% +} +\end{verbatim} +will insert section-level bookmarks. The use of \cs{currentglossary} +helps to provide unique bookmark labels in the event of multiple +glossaries. + +The \glostyle{index}-like and \glostyle{tree}-like styles +insert the pre-\gls{numberlist} space with +\begin{definition}[\DescribeMacro\glstreeprelocation] +\cs{glstreeprelocation} +\end{definition} +(which defaults to \cs{glsxtrprelocation}) for top-level items and +\begin{definition}[\DescribeMacro\glstreechildprelocation] +\cs{glstreechildprelocation} +\end{definition} +(which defaults to \cs{glstreeprelocation}) for child items. + +As from version 1.31, the \styfmt{glossaries-extra-stylemods} +package also provides: +\begin{definition}[\DescribeMacro\glstreenonamedesc] +\cs{glstreenonamedesc}\marg{label} +\end{definition} +which is used by the \glostyle{treenoname} styles to display the +pre-description separator, the description and the post-description +hook. Similarly for the symbol: +\begin{definition}[\DescribeMacro\glstreenonamesymbol] +\cs{glstreenonamesymbol}\marg{label} +\end{definition} +The above are just used for top-level entries. Child entries don't +have the name or symbol displayed for the \glostyle{treenoname} +styles, so there's only a command for the child description: +\begin{definition}[\DescribeMacro\glstreenonamechilddesc] +\cs{glstreenonamechilddesc}\marg{label} +\end{definition} + +For the \glostyle{tree} styles (but not the \glostyle{treenoname} or +\glostyle{alttree} styles), the description is displayed using: +\begin{definition}[\DescribeMacro\glstreedesc] +\cs{glstreedesc}\marg{label} +\end{definition} +and the symbol with: +\begin{definition}[\DescribeMacro\glstreesymbol] +\cs{glstreesymbol}\marg{label} +\end{definition} +Again the above two commands are just for top-level entries. The +child entries use: +\begin{definition}[\DescribeMacro\glstreechilddesc] +\cs{glstreechilddesc}\marg{label} +\end{definition} +for the description and +\begin{definition}[\DescribeMacro\glstreechildsymbol] +\cs{glstreechildsymbol}\marg{label} +\end{definition} +for the symbol. + +As from version 1.41, there are now wrapper commands for +\cs{glstreedesc} and \cs{glstreechilddesc} that check for +the description and symbol to determine whether or not to insert a +space (\cs{glstreeprelocation} or \cs{glstreechildprelocation}) +before the page list. These are: +\begin{definition}[\DescribeMacro\glstreeDescLoc] +\cs{glstreeDescLoc}\marg{label}\marg{location} +\end{definition} +for top-level entries and +\begin{definition}[\DescribeMacro\glstreeChildDescLoc] +\cs{glstreeChildDescLoc}\marg{label}\marg{location} +\end{definition} +for sub-entries. This prevents a spurious space for terms that don't +have a symbol or description but do have a location list (for +example, aliases). + +As from version 1.05, the \styfmt{glossaries-extra-stylemods} +package provides some additional commands for use with the +\glostyle{alttree} style to make it easier to modify. +These commands are only defined if the +\sty{glossary-tree} package has already been loaded, which is +typically the case unless the \pkgopt{notree} option has been used +when loading \styfmt{glossaries}. + +\begin{definition}[\DescribeMacro\gglssetwidest] +\cs{gglssetwidest}\oarg{level}\marg{name} +\end{definition} +(New to version 1.21.) +This is like \cs{glssetwidest} (provided by \sty{glossary-tree}) +but performs a global assignment. + +\begin{definition}[\DescribeMacro\eglssetwidest] +\cs{eglssetwidest}\oarg{level}\marg{name} +\end{definition} +This is like \cs{glssetwidest} +but performs a protected expansion on \meta{name}. This has +a localised effect. For a global setting, use +\begin{definition}[\DescribeMacro\xglssetwidest] +\cs{xglssetwidest}\oarg{level}\marg{name} +\end{definition} +The following only set the value if \meta{name} is wider than the +current value (new to version 1.23). Local update: +\begin{definition}[\DescribeMacro\glsupdatewidest] +\cs{glsupdatewidest}\oarg{level}\marg{name} +\end{definition} +Global update: +\begin{definition}[\DescribeMacro\gglsupdatewidest] +\cs{gglsupdatewidest}\oarg{level}\marg{name} +\end{definition} +Locale update (expands \meta{name}): +\begin{definition}[\DescribeMacro\eglsupdatewidest] +\cs{eglsupdatewidest}\oarg{level}\marg{name} +\end{definition} +Global update (expands \meta{name}): +\begin{definition}[\DescribeMacro\xglsupdatewidest] +\cs{xglsupdatewidest}\oarg{level}\marg{name} +\end{definition} + + +The widest entry value can later be retrieved using +\begin{definition}[\DescribeMacro\glsgetwidestname] +\cs{glsgetwidestname} +\end{definition} +for the top-level entries and +\begin{definition}[\DescribeMacro\glsgetwidestsubname] +\cs{glsgetwidestsubname}\marg{level} +\end{definition} +for sub-entries, where \meta{level} is the level number. + +Note that if you are using \gls{bib2gls}, you can use the +resource option \texttt{set-widest} which will try to determine the +widest name of all the selected entries. This isn't guaranteed +to work as it may depend on fonts or commands that \gls{bib2gls} +can't replicate, but it should be suitable for names that just +consist of text, and can be more efficient than iterating over all +the defined entries using \TeX. + +The command \cs{glsfindwidesttoplevelname} provided by +\sty{glossary-tree} has a CamelCase synonym: +\begin{definition}[\DescribeMacro\glsFindWidestTopLevelName] +\cs{glsFindWidestTopLevelName}\oarg{glossary list} +\end{definition} +Similar commands are also provided: +\begin{definition}[\DescribeMacro\glsFindWidestUsedTopLevelName] +\cs{glsFindWidestUsedTopLevelName}\oarg{glossary list} +\end{definition} +This has an additional check that the entry has been used. +Naturally this is only useful if the glossaries that use +the \glostyle{alttree} style occur at the end of the document. +This command should be placed just before the start of the glossary. +(Alternatively, place it at the end of the document and save +the value in the auxiliary file for the next run.) + +\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyName] +\cs{glsFindWidestUsedAnyName}\oarg{glossary list} +\end{definition} +This is like the previous command but if doesn't check the +\gloskey{parent} key. This is useful if all levels should have the +same width for the name. + +\begin{definition}[\DescribeMacro\glsFindWidestAnyName] +\cs{glsFindWidestAnyName}\oarg{glossary list} +\end{definition} +This is like the previous command but doesn't check if the entry +has been used. + +\begin{definition}[\DescribeMacro\glsFindWidestUsedLevelTwo] +\cs{glsFindWidestUsedLevelTwo}\oarg{glossary list} +\end{definition} +This is like \cs{glsFindWidestUsedTopLevelName} but also sets +the first two sub-levels as well. Any entry that has a +great-grandparent is ignored. + +\begin{definition}[\DescribeMacro\glsFindWidestLevelTwo] +\cs{glsFindWidestLevelTwo}\oarg{glossary list} +\end{definition} +This is like the previous command but doesn't check if the entry has +been used. + +\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbol] +\cs{glsFindWidestUsedAnyNameSymbol}\oarg{glossary +list}\marg{register} +\end{definition} +This is like \cs{glsFindWidestUsedAnyName} but also measures the +symbol. The length of the widest symbol is stored in +\meta{register}. + +\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbol] +\cs{glsFindWidestAnyNameSymbol}\oarg{glossary list}\marg{register} +\end{definition} +This is like the previous command but it doesn't check if the entry +has been used. + +\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbolLocation] +\cs{glsFindWidestUsedAnyNameSymbolLocation}\oarg{glossary +list}\marg{symbol register}\marg{location register} +\end{definition} +This is like \cs{glsFindWidestUsedAnyNameSymbol} but also +measures the \gls{numberlist}. This requires +\ics{glsentrynumberlist} (see the \styfmt{glossaries} user manual). +The length of the widest symbol is stored in \meta{symbol register} +and the length of the widest \gls*{numberlist} is stored in +\meta{location register}. + +\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbolLocation] +\cs{glsFindWidestAnyNameSymbolLocation}\oarg{glossary +list}\marg{symbol register}\marg{location register} +\end{definition} +This is like the previous command but it doesn't check if the entry +has been used. + +\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameLocation] +\cs{glsFindWidestUsedAnyNameLocation}\oarg{glossary +list}\marg{register} +\end{definition} +This is like \cs{glsFindWidestUsedAnyNameSymbolLocation} but doesn't +measure the symbol. The length of the widest \gls{numberlist} +is stored in \meta{register}. + +\begin{definition}[\DescribeMacro\glsFindWidestAnyNameLocation] +\cs{glsFindWidestAnyNameLocation}\oarg{glossary +list}\marg{register} +\end{definition} +This is like the previous command but doesn't check if the entry has +been used. + +The layout of the symbol, description and \gls{numberlist} +is governed by +\begin{definition}[\DescribeMacro\glsxtralttreeSymbolDescLocation] +\cs{glsxtralttreeSymbolDescLocation}\marg{label}\marg{number list} +\end{definition} +for top-level entries and +\begin{definition}[\DescribeMacro\glsxtralttreeSubSymbolDescLocation] +\cs{glsxtralttreeSubSymbolDescLocation}\marg{label}\marg{number list} +\end{definition} +for sub-entries. + +There is now a user level command that performs the initialisation +for the \glostyle{alttree} style: +\begin{definition}[\DescribeMacro\glsxtralttreeInit] +\cs{glsxtralttreeInit} +\end{definition} + +The paragraph indent for subsequent paragraphs in multi-paragraph +descriptions is provided by the length +\begin{definition}[\DescribeMacro\glsxtrAltTreeIndent] +\cs{glsxtrAltTreeIndent} +\end{definition} + +For additional commands that are available with the +\glostyle{alttree} style, see the documented code +(\texttt{glossaries-extra-code.pdf}). For examples, see +the accompanying sample files \texttt{sample-alttree.tex}, +\texttt{sample-alttree-sym.tex} and +\texttt{sample-alttree-marginpar.tex}. + +\chapter{Abbreviations} +\label{sec:abbreviations} + +The new abbreviation system provided by \styfmt{glossaries-extra} +is more flexible than the acronym handling provided by the +base \styfmt{glossaries} package. The \styfmt{glossaries-extra} +package modifies the underlying formatting used by +\cs{gls} (and its variants) so that terms that are recognised as +abbreviations can have their formatting dealt with by the style. You +therefore need to select an abbreviation style that ensures that +\cs{gls} (and its variants) displays the desired output. + +\begin{important} +Don't use commands like \cs{glstext} or \cs{glsfirst} with +abbreviations as they aren't flexible enough to handle some +abbreviation styles and unexpected results may occur. Use commands +like \cs{glsfmtshort} or \cs{glsfmtlong} in section headings or +captions instead of \cs{gls}. If you don't want the full form to +show on first use of \cs{gls} use one of the \qt{nolong} or +\qt{noshort} styles. +\end{important} + +Abbreviations include acronyms (words formed from initial letters, +such as \qt{laser}), +initialisms (initial letters of a phrase, such as \qt{html}, that +aren't pronounced as words) and contractions (where +parts of words are omitted, often replaced by an apostrophe, such as +\qt{don't}). +The \qt{acronym} code provided by the \styfmt{glossaries} package is +misnamed as it's more often than not used for initialisms instead. +Acronyms tend not to be \emph{expanded} on \gls{firstuse} (although they may +need to be \emph{described} for readers unfamiliar with the term). They are therefore more like a regular term, +which may or may not require a description in the glossary. + +The \styfmt{glossaries-extra} package corrects this misnomer, and +provides better abbreviation handling, with +\begin{definition}[\DescribeMacro\newabbreviation] +\cs{newabbreviation}\oarg{options}\marg{label}\marg{short}\marg{long} +\end{definition} + +This sets the \gloskey{category} key to \texttt{abbreviation} by +default, but that value may be overridden in \meta{options}. +The category may have attributes that modify the way abbreviations +are defined. For example, the \catattr{insertdots} attribute will +automatically insert full stops (periods) into \meta{short} or the +\catattr{noshortplural} attribute will set the default value +of the \gloskey{shortplural} key to just \meta{short} (without +appending the plural suffix). See \sectionref{sec:categories} for +further details. + +See \sectionref{sec:nested} regarding the pitfalls of using +commands like \ics{gls} or \ics{glsxtrshort} within +\meta{short} or \meta{long}. + +\begin{important} +Make sure that you set the category attributes before defining new +abbreviations or they may not be correctly applied. +\end{important} + +The \ics{newacronym} command provided by the \styfmt{glossaries} +package is redefined by \styfmt{glossaries-extra} to use +\cs{newabbreviation} with the \gloskey{category} set to +\texttt{acronym} (see also \sectionref{sec:acronymmods}) so +\begin{definition}[\DescribeMacro\newacronym] +\cs{newacronym}\oarg{options}\marg{label}\marg{short}\marg{long} +\end{definition} +is now equivalent to +\begin{display}\raggedright\ttfamily +\cs{newabbreviation}[type=\cs{acronymtype},category=acronym,\meta{options}]\marg{label}\marg{short}\marg{long} +\end{display} + +\begin{sloppypar} +The \cs{newabbreviation} command is superficially similar to the +\styfmt{glossaries} package's \cs{newacronym} but you can apply +different styles to different categories. The default style is +\abbrstyle{short-nolong} for entries in the \category{acronym} category and +\abbrstyle{short-long} for entries in the \category{abbreviation} +category. (These aren't the same as the acronym styles provided by +the \styfmt{glossaries} package, although they may produce similar +results.) +\end{sloppypar} + +The way the abbreviations are displayed by commands like \cs{gls} +varies according to the abbreviation style. The styles are set +according to the entry's category so, unlike the base +\styfmt{glossaries} package, you can have different abbreviation +styles within the same glossary. + +There are two types of full forms. The display full form, which is +used on \gls{firstuse} by commands like \ics{gls} and the inline full +form, which is used by commands like \ics{glsxtrfull}. +For some of the abbreviation styles, such as \abbrstyle{long-short}, the display and inline forms +are the same. In the case of styles such as \abbrstyle{short-nolong} or +\abbrstyle{short-footnote}, the display and inline full forms are different. + +These formatting commands aren't stored in the \gloskey{short}, +\gloskey{shortplural}, \gloskey{long} or \gloskey{longplural} +fields, which means they won't be used within commands like +\cs{glsentryshort} (but they are used within commands like +\cs{glsxtrshort} and \cs{glsfmtshort}). +Note that \ics{glsxtrlong} and the case-changing variants don't use +\cs{glsfirstlongfont}. + +You can apply the formatting command used for the short form +to some arbitrary text using +\begin{definition}[\DescribeMacro\glsuseabbrvfont] +\cs{glsuseabbrvfont}\marg{text}\marg{category} +\end{definition} +where \meta{category} is the category label that identifies +the abbreviation style. Similarly for the formatting command +use by the long form: +\begin{definition}[\DescribeMacro\glsuselongfont] +\cs{glsuselongfont}\marg{text}\marg{category} +\end{definition} + +\section{Tagging Initials} +\label{sec:tagging} + +If you would like to tag the initial letters in the long form +such that those letters are underlined in the glossary but +not in the main part of the document, you can use +\begin{definition}[\DescribeMacro\GlsXtrEnableInitialTagging] +\cs{GlsXtrEnableInitialTagging}\marg{categories}\marg{cs} +\end{definition} +before you define your abbreviations. + +This command (robustly) defines \meta{cs} (a control sequence) +to accept a single argument, which is the letter (or letters) +that needs to be tagged. The normal behaviour of this command +within the document is to simply do its argument, but in the +glossary it's activated for those categories that have +the \catattr{tagging} attribute set to \qt{true}. For those +cases it will use +\begin{definition}[\DescribeMacro\glsxtrtagfont] +\cs{glsxtrtagfont}\marg{text} +\end{definition} +This command defaults to \ics{underline}\marg{text} +but may be redefined as required. + +The control sequence \meta{cs} can't already be defined when +used with the unstarred version of +\cs{GlsXtrEnableInitialTagging} for safety reasons. +The starred version will overwrite any previous definition +of \meta{cs}. As with redefining any commands, ensure that +you don't redefine something important. In fact, just forget +the existence of the starred version and let's pretend I didn't +mention it. + +The first argument of \cs{GlsXtrEnableInitialTagging} is a +comma-separated list of category names. The \catattr{tagging} +attribute will automatically be set for those categories. +You can later set this attribute for other categories (see +\sectionref{sec:categories}) but this must be done before the +glossary is displayed. + +The accompanying sample file \texttt{sample-mixtures.tex} +uses initial tagging for both the \category{acronym} and +\category{abbreviation} categories: +\begin{verbatim} +\GlsXtrEnableInitialTagging{acronym,abbreviation}{\itag} +\end{verbatim} +This defines the command \cs{itag} which can be used in the +definitions. For example: +\begin{verbatim} +\newacronym + [description={a system for detecting the location and + speed of ships, aircraft, etc, through the use of radio + waves}% description of this term + ] + {radar}% identifying label + {radar}% short form (i.e. the word) + {\itag{ra}dio \itag{d}etection \itag{a}nd \itag{r}anging} + +\newabbreviation{xml}{XML} + {e\itag{x}tensible \itag{m}arkup \itag{l}anguage} +\end{verbatim} +The underlining of the tagged letters only occurs in the +glossary and then only for entries with the \catattr{tagging} +attribute set. + +\section{Abbreviation Styles} +\label{sec:abbrstyle} + +The abbreviation style must be set before abbreviations are defined +using: +\begin{definition}[\DescribeMacro\setabbreviationstyle] +\cs{setabbreviationstyle}\oarg{category}\marg{style-name} +\end{definition} +where \meta{style-name} is the name of the style and \meta{category} +is the category label (\texttt{abbreviation} by default). New +abbreviations will pick up the current style according to their +given category. If there is no style set for the category, the +fallback is the style for the \texttt{abbreviation} category. +Some styles may automatically modify one or more of the attributes +associated with the given category. For example, the +\abbrstyle{long-noshort} and \abbrstyle{short-nolong} styles set the +\catattr{regular} attribute to \texttt{true}. + +\begin{important} +If you want to apply different styles to groups of abbreviations, +assign a different category to each group and set the style for the +given category. +\end{important} + +Note that \ics{setacronymstyle} is disabled by +\styfmt{glossaries-extra}. Use +\begin{alltt} +\cs{setabbreviationstyle}[acronym]\marg{style-name} +\end{alltt} +instead. The original acronym interface can be restored with +\ics{RestoreAcronyms} (see \sectionref{sec:acronymmods}). However the +original acronym interface is incompatible with all the commands +described here. + +Abbreviations can be used with the standard \styfmt{glossaries} +commands, such as \ics{gls}, but don't use the acronym commands +like \ics{acrshort} (which use \ics{acronymfont}). The short form can be +produced with: +\begin{definition}[\DescribeMacro\glsxtrshort] +\cs{glsxtrshort}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(Use this instead of \ics{acrshort}.) + +The long form can be produced with +\begin{definition}[\DescribeMacro\glsxtrlong] +\cs{glsxtrlong}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(Use this instead of \ics{acrlong}.) + +The \emph{inline} full form can be produced with +\begin{definition}[\DescribeMacro\glsxtrfull] +\cs{glsxtrfull}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(This this instead of \ics{acrfull}.) + +\begin{important} +In general, it's best not to use commands like \ics{glsfirst} +for abbreviations, especially if you use the \meta{insert} +optional argument. Use either \cs{gls} (possibly with a reset) +or \cs{glsxtrfull}. +\end{important} + +As mentioned earlier, the inline full form may not necessarily match the format used on +\gls{firstuse} with \cs{gls}. For example, the +\abbrstyle{short-nolong} style +only displays the short form on \gls{firstuse}, but the full +form will display the long form followed by the short form in +parentheses. + +\begin{important} +If you want to use an abbreviation in a chapter or section +title, use the commands described in \sectionref{sec:headtitle} +instead. +\end{important} + +The arguments \meta{options}, \meta{label} and \meta{insert} are the +same as for commands such as \cs{glstext}. There are also analogous +case-changing commands: + +First letter upper case short form: +\begin{definition}[\DescribeMacro\Glsxtrshort] +\cs{Glsxtrshort}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +First letter upper case long form: +\begin{definition}[\DescribeMacro\Glsxtrlong] +\cs{Glsxtrlong}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +First letter upper case inline full form: +\begin{definition}[\DescribeMacro\Glsxtrfull] +\cs{Glsxtrfull}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +All upper case short form: +\begin{definition}[\DescribeMacro\Glsxtrshort] +\cs{GLSxtrshort}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +All upper case long form: +\begin{definition}[\DescribeMacro\Glsxtrlong] +\cs{GLSxtrlong}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +All upper case inline full form: +\begin{definition}[\DescribeMacro\GLSxtrfull] +\cs{GLSxtrfull}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +Plural forms are also available. + +Short form plurals: +\begin{definition}[\DescribeMacro\glsxtrshortpl] +\cs{glsxtrshortpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\Glsxtrshortpl] +\cs{Glsxtrshortpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\GLSxtrshortpl] +\cs{GLSxtrshortpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +Long form plurals: +\begin{definition}[\DescribeMacro\glsxtrlongpl] +\cs{glsxtrlongpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\Glsxtrlongpl] +\cs{Glsxtrlongpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\GLSxtrlongpl] +\cs{GLSxtrlongpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +Full form plurals: +\begin{definition}[\DescribeMacro\glsxtrfullpl] +\cs{glsxtrfullpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\Glsxtrfullpl] +\cs{Glsxtrfullpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\GLSxtrfullpl] +\cs{GLSxtrfullpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} + +\begin{important} +Be careful about using \cs{glsentryfull}, \cs{Glsentryfull}, +\cs{glsentryfullpl} and \cs{Glsentryfullpl}. These commands will use +the currently applied style rather than the style in use when the +entry was defined. If you have mixed styles, you'll need to use +\ics{glsxtrfull} instead. Similarly for \cs{glsentryshort} etc. +\end{important} + +\section{Shortcut Commands} +\label{sec:abbrshortcuts} + +The abbreviation shortcut commands can be enabled using +the package option \pkgopt[abbreviation]{shortcuts} +(or \pkgopt[abbr]{shortcuts}) or \pkgopt[ac]{shortcuts}. +(You can use both settings at the same time.) +The provided shortcut commands listed in +\tableref{tab:abbrshortcuts}. + +\begin{table}[htbp] +\caption{Abbreviation Shortcut Commands} +\label{tab:abbrshortcuts} +\centering +\begin{tabular}{lll} +\bfseries Shortcut & +\bfseries Shortcut & +\bfseries Equivalent Command\\ +\bfseries (\pkgopt[abbreviation]{shortcuts}) & +\bfseries (\pkgopt[ac]{shortcuts})\\ +\ics{ab} & \ics{ac} & \ics{cgls}\\ +\ics{abp} & \ics{acp} & \ics{cglspl}\\ +\ics{as} & \ics{acs} & \ics{glsxtrshort}\\ +\ics{asp} & \ics{acsp} & \ics{glsxtrshortpl}\\ +\ics{al} & \ics{acl} & \ics{glsxtrlong}\\ +\ics{alp} & \ics{aclp} & \ics{glsxtrlongpl}\\ +\ics{af} & \ics{acf} & \ics{glsxtrfull}\\ +\ics{afp} & \ics{acfp} & \ics{glsxtrfullpl}\\ +\ics{Ab} & \ics{Ac} & \ics{cgls}\\ +\ics{Abp} & \ics{Acp} & \ics{cglspl}\\ +\ics{As} & \ics{Acs} & \ics{Glsxtrshort}\\ +\ics{Asp} & \ics{Acsp} & \ics{Glsxtrshortpl}\\ +\ics{Al} & \ics{Acl} & \ics{Glsxtrlong}\\ +\ics{Alp} & \ics{Aclp} & \ics{Glsxtrlongpl}\\ +\ics{Af} & \ics{Acf} & \ics{Glsxtrfull}\\ +\ics{Afp} & \ics{Acfp} & \ics{Glsxtrfullpl}\\ +\ics{AB} & \ics{AC} & \ics{cGLS}\\ +\ics{ABP} & \ics{ACP} & \ics{cGLSpl}\\ +\ics{AS} & \ics{ACS} & \ics{GLSxtrshort}\\ +\ics{ASP} & \ics{ACSP} & \ics{GLSxtrshortpl}\\ +\ics{AL} & \ics{ACL} & \ics{GLSxtrlong}\\ +\ics{ALP} & \ics{ACLP} & \ics{GLSxtrlongpl}\\ +\ics{AF} & \ics{ACF} & \ics{GLSxtrfull}\\ +\ics{AFP} & \ics{ACFP} & \ics{GLSxtrfullpl}\\ +\ics{newabbr} & \ics{newabbr} & \ics{newabbreviation} +\end{tabular} +\end{table} + +\section{Predefined Abbreviation Styles} +\label{sec:predefabbrvstyles} + +There are two types of abbreviation styles: those that treat the +abbreviation as a regular entry (so that \ics{gls} uses +\ics{glsgenentryfmt}) and those that don't treat the abbreviation as +a regular entry (so that \ics{gls} uses \ics{glsxtrgenabbrvfmt}). + +The regular entry abbreviation styles set the \catattr{regular} +attribute to \qt{true} for the category assigned to each +abbreviation with that style. This means that on \gls{firstuse}, +\ics{gls} uses the value of the \gloskey{first} field and on +subsequent use \ics{gls} uses the value of the \gloskey{text} field +(and analogously for the plural and case-changing versions). The +\gloskey{short} and \gloskey{long} fields are set as appropriate +and may be accessed through commands like \ics{glsxtrshort}. + +The other abbreviation styles don't modify the \catattr{regular} +attribute. The \gloskey{first} and \gloskey{text} fields (and their +plural forms) are set and can be accessed through commands like +\cs{glsfirst}, but they aren't used by commands like \ics{gls}, +which instead use the short form (stored in the \gloskey{short} key) +and the display full format (through commands like +\ics{glsxtrfullformat} that are defined by the style). + +In both cases, the \gls{firstuse} of \ics{gls} may not match the +text produced by \ics{glsfirst} (and likewise for the plural +and case-changing versions). + +The sample file \texttt{sample-abbr-styles.tex} demonstrates all +predefined styles described here. + +\begin{important} +For the \qt{sc} styles that use \ics{textsc}, be careful about your choice +of fonts as some only have limited support. For +example, you may not be able to combine bold and small-caps. I +recommend that you at least use the \sty{fontenc} package with the +\pkgoptfmt{T1} option or something similar. +\end{important} + +The parenthetical styles, such as \abbrstyle{long-short}, +use +\begin{definition}[\DescribeMacro\glsxtrparen] +\cs{glsxtrparen}\marg{text} +\end{definition} +to set the parenthetical material. This just puts parentheses around +the text: (\meta{text}). + +The basic abbreviation styles, such as \abbrstyle{long-short} +and \abbrstyle{short-long} use +\begin{definition}[\DescribeMacro\glsabbrvdefaultfont] +\cs{glsabbrvdefaultfont}\marg{text} +\end{definition} +for the short form. This just does \meta{text} by default. +(That is, no font change is applied.) On first use, +\begin{definition}[\DescribeMacro\glsfirstabbrvdefaultfont] +\cs{glsfirstabbrvdefaultfont}\marg{text} +\end{definition} +is used instead. By default, this just does +\cs{glsabbrvdefaultfont}. The long form is formatted according to +\begin{definition}[\DescribeMacro\glslongdefaultfont] +\cs{glslongdefaultfont}\marg{text} +\end{definition} +which again just does \meta{text} (no font change). On first use, +\begin{definition}[\DescribeMacro\glsfirstlongdefaultfont] +\cs{glsfirstlongdefaultfont}\marg{text} +\end{definition} +is used instead. This just does \cs{glslongdefaultfont}. +The plural suffix used for the short form is given by +\begin{definition}[\DescribeMacro\glsxtrabbrvpluralsuffix] +\cs{glsxtrabbrvpluralsuffix} +\end{definition} +which defaults to \ics{glspluralsuffix}. + +The small-cap styles, such as \abbrstyle{long-short-sc} +and \abbrstyle{short-sc-long}, use +\begin{definition}[\DescribeMacro\glsabbrvscfont] +\cs{glsabbrvscfont}\marg{text} +\end{definition} +which uses \cs{textsc}.\footnote{For compatibility with earlier +versions, \cs{glsabbrvscfont} is defined to \cs{glsxtrscfont}, +which is defined to use \cs{textsc}. Direct use of +\cs{glsxtrscfont} is now deprecated. Likewise for similar commands.} +On first use +\begin{definition}[\DescribeMacro\glsabbrvdefaultfont] +\cs{glsfirstabbrvscfont}\marg{text} +\end{definition} +is used instead. This uses \cs{glsabbrvscfont} by default. +So redefine, \cs{glsabbrvscfont} to change first and subsequent uses or +\cs{glsfirstabbrvscfont} to change just the first use. + +The long form for the small-cap styles uses \cs{glslongdefaultfont} +or \cs{glsfirstlongdefaultfont}, as with the basic style. +The suffix is given by +\begin{definition}[\DescribeMacro\glsxtrscsuffix] +\cs{glsxtrscsuffix} +\end{definition} +This is defined as +\begin{verbatim} +\newcommand*{\glsxtrscsuffix}{\glstextup{\glsxtrabbrvpluralsuffix}} +\end{verbatim} +The \ics{glstextup} command is provided by \styfmt{glossaries} +and is used to switch off the small caps font for the suffix. +If you override the default short plural using the +\gloskey{shortplural} key when you define the abbreviation +you will need to make the appropriate adjustment if necessary. +(Remember that the default plural suffix behaviour can be modified +through the use of the \catattr{aposplural} and +\catattr{noshortplural} attributes. See +\sectionref{sec:categories} for further details.) + +The small styles, such as \abbrstyle{long-short-sm} +and \abbrstyle{short-sm-long}, use +\begin{definition}[\DescribeMacro\glsabbrvsmfont] +\cs{glsabbrvsmfont}\marg{text} +\end{definition} +which uses \cs{textsmaller}. (This requires the \sty{relsizes} +package, which isn't loaded by \styfmt{glossaries-extra}, so must be +loaded explicitly.) +On first use +\begin{definition}[\DescribeMacro\glsfirstabbrvsmfont] +\cs{glsfirstabbrvsmfont}\marg{text} +\end{definition} +is used instead. This uses \cs{glsabbrvsmfont} by default. + +The long form for the smaller styles uses \cs{glslongdefaultfont} +or \cs{glsfirstlongdefaultfont}, as with the basic style. +The suffix is given by +\begin{definition}[\DescribeMacro\glsxtrsmsuffix] +\cs{glsxtrsmsuffix} +\end{definition} +which defaults to just \cs{glsxtrabbrvpluralsuffix}. + +The \qt{short-em} (emphasize short) styles, such as +\abbrstyle{long-short-em} or \abbrstyle{short-em-long}, use +\begin{definition}[\DescribeMacro\glsabbrvemfont] +\cs{glsabbrvemfont}\marg{text} +\end{definition} +On first use +\begin{definition}[\DescribeMacro\glsfirstabbrvemfont] +\cs{glsfirstabbrvemfont}\marg{text} +\end{definition} +is used instead. This uses \cs{glsabbrvemfont} by default. +The suffix is given by +\begin{definition}[\DescribeMacro\glsxtremsuffix] +\cs{glsxtremsuffix} +\end{definition} +which defaults to just \cs{glsxtrabbrvpluralsuffix}. +The long form is as for the basic style unless the style +is a \qt{long-em} style. + +The \qt{long-em} (emphasize long) styles, such as +\abbrstyle{long-em-short-em} or \abbrstyle{short-em-long-em}, use +\begin{definition}[\DescribeMacro\glsfirstlongemfont] +\cs{glsfirstlongemfont}\marg{long-form} +\end{definition} +instead of \cs{glsfirstlongdefaultfont}\marg{long-form} and +\begin{definition}[\DescribeMacro\glslongemfont] +\cs{glslongemfont}\marg{long-form} +\end{definition} +instead of \cs{glslongdefaultfont}\marg{long-form}. The first form +\cs{glsfirstlongemfont} is initialised to use \cs{glslongemfont}. + +The user styles have similar commands: +\begin{definition}[\DescribeMacro\glsabbrvuserfont] +\cs{glsabbrvuserfont}\marg{text} +\end{definition} +for the short form, +\begin{definition}[\DescribeMacro\glsfirstabbrvuserfont] +\cs{glsfirstabbrvuserfont}\marg{text} +\end{definition} +for the first use short form, +\begin{definition}[\DescribeMacro\glslonguserfont] +\cs{glslonguserfont}\marg{text} +\end{definition} +for the long form, +\begin{definition}[\DescribeMacro\glsfirstlonguserfont] +\cs{glsfirstlonguserfont}\marg{text} +\end{definition} +for the first use long form, and +\begin{definition}[\DescribeMacro\glsxtrusersuffix] +\cs{glsxtrusersuffix} +\end{definition} +for the short plural suffix. + +Similarly for the hyphen styles: +\begin{definition}[\DescribeMacro\glsabbrvhyphenfont] +\cs{glsabbrvhyphenfont}\marg{text} +\end{definition} +for the short form, +\begin{definition}[\DescribeMacro\glsfirstabbrvhyphenfont] +\cs{glsfirstabbrvhyphenfont}\marg{text} +\end{definition} +for the first use short form, +\begin{definition}[\DescribeMacro\glslonghyphenfont] +\cs{glslonghyphenfont}\marg{text} +\end{definition} +for the long form, +\begin{definition}[\DescribeMacro\glsfirstlonghyphenfont] +\cs{glsfirstlonghyphenfont}\marg{text} +\end{definition} +for the first use long form, and +\begin{definition}[\DescribeMacro\glsxtrhyphensuffix] +\cs{glsxtrhyphensuffix} +\end{definition} +for the short plural suffix. + +Similarly for the \qt{only} styles, such as +\abbrstyle{long-only-short-only}: +\begin{definition}[\DescribeMacro\glsabbrvonlyfont] +\cs{glsabbrvonlyfont}\marg{text} +\end{definition} +for the short form, +\begin{definition}[\DescribeMacro\glsfirstabbrvonlyfont] +\cs{glsfirstabbrvonlyfont}\marg{text} +\end{definition} +for the first use short form, +\begin{definition}[\DescribeMacro\glslongonlyfont] +\cs{glslongonlyfont}\marg{text} +\end{definition} +for the long form, +\begin{definition}[\DescribeMacro\glsfirstlongonlyfont] +\cs{glsfirstlongonlyfont}\marg{text} +\end{definition} +for the first use long form, and +\begin{definition}[\DescribeMacro\glsxtronlysuffix] +\cs{glsxtronlysuffix} +\end{definition} +for the short plural suffix. + +Note that by default inserted material (provided in the final +optional argument of commands like \cs{gls}), is placed outside the +font command in the predefined styles. To move it inside, use: +\begin{definition}[\DescribeMacro\glsxtrinsertinsidetrue] +\cs{glsxtrinsertinsidetrue} +\end{definition} +This applies to all the predefined styles. For example: +\begin{verbatim} +\setabbreviationstyle{long-short} +\renewcommand*{\glsfirstlongdefaultfont}[1]{\emph{#1}} +\glsxtrinsertinsidetrue +\end{verbatim} +This will make the long form and the inserted text emphasized, +whereas the default (without \cs{glsxtrinsertinsidetrue}) would +place the inserted text outside of the emphasized font. + +Note that for some styles, such as the \abbrstyle{short-long}, the +inserted text would be placed inside the font command for the short +form (rather than the long form in the above example). + +Remember that \cs{textsc} renders \emph{lowercase} letters as small +capitals. Uppercase letters are rendered as normal uppercase +letters, so if you specify the short form in uppercase, you won't +get small capitals unless you redefine \cs{glsabbrvscfont} to +convert its argument to lowercase. For example: +\begin{verbatim} +\renewcommand*{\glsabbrvscfont}[1]{\textsc{\MakeLowercase{#1}}} +\end{verbatim} + +If you want to +easily switch between the \qt{sc} and \qt{sm} styles, you may find +it easier to redefine this command to convert case: +\begin{verbatim} +\renewcommand*{\glsabbrvscfont}[1]{\textsc{\MakeTextLowercase{#1}}} +\renewcommand*{\glsabbrvsmfont}[1]{\textsmaller{\MakeTextUppercase{#1}}} +\end{verbatim} + +Some of the styles use +\begin{definition}[\DescribeMacro\glsxtrfullsep] +\cs{glsxtrfullsep}\marg{label} +\end{definition} +as a separator between the long and short forms. This is defined as +a space by default, but may be changed as required. For example: +\begin{verbatim} +\renewcommand*{\glsxtrfullsep}[1]{~} +\end{verbatim} +or +\begin{verbatim} +\renewcommand*{\glsxtrfullsep}[1]{\glsacspace{#1}} +\end{verbatim} + +The new naming scheme for abbreviation styles is as follows: +\begin{itemize} +\item +\meta{field1}[\texttt{-}\meta{modifier1}]\texttt{-}[post]\meta{field2}[\texttt{-}\meta{modifier2}][\texttt{-user}] + +This is for the parenthetical styles. The \texttt{-}\meta{modifier} parts may +be omitted. These styles display \meta{field1} followed by +\meta{field2} in parentheses. If \meta{field1} or \meta{field2} starts +with \qt{no} then that element is omitted from the display style (no +parenthetical part) but is included in the inline style. + +If the \texttt{-}\meta{modifier} part is present, then the field has +a font changing command applied to it. The special modifier +\texttt{-only} indicates that field is only present according to +whether or not the entry has been used. + +If \texttt{post} is present then \meta{field2} is +placed after the \gls{linktext} using the post-link hook. + +If the \texttt{-user} part is present, then the \gloskey{user1} +value, if provided, is inserted into the parenthetical material . +(The field used for the inserted material may be changed.) + +Examples: + \begin{itemize} + \item\abbrstyle{long-noshort-sc}: \meta{field1} is the long +form, the short form is set in smallcaps but omitted in the display +style. + \item\abbrstyle{long-em-short-em}: both the long form and the +short form are emphasized. The short form is in parentheses. + \item\abbrstyle{long-short-em}: the +short form is emphasized but not the long form. The short form is in parentheses. + \item\abbrstyle{long-short-user}: if the \gloskey{user1} key has +been set, this produces the style \meta{long} (\meta{short}, +\meta{user1}) otherwise it just produces \meta{long} (\meta{short}). + + \item\abbrstyle{long-hyphen-postshort-hyphen}: the short +form and the inserted material (provided by the final optional +argument of commands like \cs{gls}) is moved to the post-link hook. +The long form is formatted according to \cs{glslonghyphenfont} +(or \cs{glsfirstlonghyphenfont} on first use). +The short form is formatted according to \cs{glsabbrvhyphenfont} +(or \cs{glsfirstabbrvhyphenfont} on first use). + \end{itemize} + +\item \meta{style}\texttt{-noreg} + +Some styles set the \catattr{regular} attribute. In some cases, +there's a version of the style that doesn't set this attribute. +For example, \abbrstyle{long-em-noshort-em} sets the +\catattr{regular} attribute. The +\abbrstyle{long-em-noshort-em-noreg} style is a minor variation +that style that doesn't set the attribute. + +There are a few \qt{noshort} styles, such as +\abbrstyle{long-hyphen-noshort-noreg}, that have +\qt{-noreg} version without a regular version. This is because the +style won't work properly with the \catattr{regular} set, but the +naming scheme is maintained for consistency with the other +\qt{noshort} styles. + +\item +\meta{field1}[\texttt{-}\meta{modifier1}]\texttt{-}[\texttt{post}]\texttt{footnote} + +The display style uses \meta{field1} followed by a footnote with the +other field in it. If \texttt{post} is present then the footnote is +placed after the \gls{linktext} using the post-link hook. +The inline style does \meta{field1} followed by the other field in +parentheses. + +If \texttt{-}\meta{modifier1} is present, \meta{field1} has a +font-changing command applied to it. + +Examples: +\begin{itemize} +\item \abbrstyle{short-footnote}: short form in the text with the +long form in the footnote. +\item \abbrstyle{short-sc-postfootnote}: short form in smallcaps +with the long form in the footnote outside of the \gls{linktext}. +\end{itemize} + +\begin{important} +Take care with the footnote styles. Remember that there are some +situations where \ics{footnote} doesn't work. +\end{important} + +\item \meta{style}\texttt{-desc} + +Like \meta{style} but the \gloskey{description} key must be provided +when defining abbreviations with this style. + +Examples: +\begin{itemize} + +\item \abbrstyle{short-long-desc}: like \abbrstyle{short-long} but +requires a description. +\item \abbrstyle{short-em-footnote-desc}: like +\abbrstyle{short-em-footnote} but requires a description. +\end{itemize} +\end{itemize} + +Not all combinations that fit the above syntax are provided. +Pre-version 1.04 styles that didn't fit this naming scheme are either +provided with a synonym (where the former name wasn't ambiguous) or +provided with a deprecated synonym (where the former name was +confusing). +The deprecated style names generate a warning using: +\begin{definition}[\DescribeMacro\GlsXtrWarnDeprecatedAbbrStyle] +\cs{GlsXtrWarnDeprecatedAbbrStyle}\marg{old-name}\marg{new-name} +\end{definition} +where \meta{old-name} is the deprecated name and \meta{new-name} is +the preferred name. You can suppress these warnings by redefining +this command to do nothing. + +\subsection{Predefined Abbreviation Styles that Set the Regular +Attribute} +\label{sec:predefregabbrvstyles} + +The following abbreviation styles set the \catattr{regular} +attribute to \qt{true} for all categories that have abbreviations +defined with any of these styles. + +\begin{description} +\item[\abbrstyledef{short-nolong}] +This only displays the short form on \gls{firstuse}. The \gloskey{name} +is set to the short form through the command +\begin{definition}[\DescribeMacro\glsxtrshortnolongname] +\cs{glsxtrshortnolongname} +\end{definition} +(Similarly for the other +\texttt{short}\meta{modifier}\texttt{-nolong}\meta{modifier} styles, +unless indicated otherwise.) +This command is expanded as the entry is defined, so any +redefinition must be done before \cs{newabbreviation} (or +\cs{newacronym}) for it to take effect. Make sure to \cs{protect} +any formatting commands (or anything else that shouldn't be expanded). + +The \gloskey{description} is set to the +long form. The inline full form displays +\meta{short} (\meta{long}). The long form on its own can be +displayed through commands like \ics{glsxtrlong}. + +\item[\abbrstyledef{short}] A synonym for \abbrstyle{short-nolong}. + +\item[\abbrstyledef{nolong-short}] Like \abbrstyle{short-nolong} +but the inline full form displays +\meta{long} (\meta{short}). + +\item[\abbrstyledef{short-sc-nolong}] +Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont} (which defaults to \cs{textsc}). + +\item[\abbrstyledef{short-sc}] A synonym for \abbrstyle{short-sc-nolong} + +\item[\abbrstyledef{nolong-short-sc}] Like \abbrstyle{short-sc-nolong} +but the inline full form displays +\meta{long} (\meta{short}). The name is still obtained from +\cs{glsxtrshortnolongname} (similarly for the other styles in the +form \texttt{nolong}\meta{modifier}\texttt{-short}\meta{modifier} +unless indicated otherwise). + +\item[\abbrstyledef{short-sm-nolong}] +Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont} (which defaults to \cs{textsmaller}). + +\item[\abbrstyledef{short-sm}] A synonym for \abbrstyle{short-sm-nolong}. + +\item[\abbrstyledef{nolong-short-sm}] Like \abbrstyle{short-sm-nolong} +but the inline full form displays +\meta{long} (\meta{short}). + +\item[\abbrstyledef{short-em-nolong}] +Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + +\item[\abbrstyledef{short-em}] A synonym for \abbrstyle{short-em-nolong} + +\item[\abbrstyledef{nolong-short-em}] Like \abbrstyle{short-em-nolong} +but the inline full form displays +\meta{long} (\meta{short}). + +\item[\abbrstyledef{short-nolong-desc}] +Like the \abbrstyle{short-nolong} style, but the \gloskey{name} is set to +the full form obtained by expanding +\begin{definition}[\DescribeMacro\glsxtrshortdescname] +\cs{glsxtrshortdescname} +\end{definition} +(Similarly for the other +\texttt{short}\meta{modifier}\texttt{-nolong}\meta{modifier}\texttt{-desc} +styles, unless indicated otherwise.) This command is expanded when the entry is defined, so +\cs{protect} fragile and formatting commands and only redefine this +command before \cs{newabbreviation} (or \cs{newacronym}). + +The \gloskey{description} must be supplied by the +user. You may prefer to use the \abbrstyle{short-nolong} style with the +post-description hook set to display the long form and override +the \gloskey{description} key. (See the sample file +\texttt{sample-acronym-desc.tex}.) + +\item[\abbrstyledef{short-desc}] A synonym for +\abbrstyle{short-nolong-desc}. + +\item[\abbrstyledef{short-sc-nolong-desc}] +Like \abbrstyle{short-nolong} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont} (which defaults to \cs{textsc}). + +\item[\abbrstyledef{short-sc-desc}] A synonym for +\abbrstyle{short-sc-nolong-desc}. + +\item[\abbrstyledef{short-sm-nolong-desc}] +Like \abbrstyle{short-nolong-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont} (which defaults to \cs{textsmaller}). + +\item[\abbrstyledef{short-sm-desc}] A synonym for +\abbrstyle{short-sm-nolong-desc}. + +\item[\abbrstyledef{short-em-nolong-desc}] +Like \abbrstyle{short-nolong-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + +\item[\abbrstyledef{short-em-desc}] A synonym for +\abbrstyle{short-em-nolong-desc}. + +\item[\abbrstyledef{long-noshort-desc}] +This style only displays the long form, regardless of first or +subsequent use of commands \ics{gls}. The short form may be +accessed through commands like \ics{glsxtrshort}. The inline full +form displays \meta{long} (\meta{short}). + +The \gloskey{sort} key are set to the long form. +The \gloskey{name} key is also set to the long form, but this is +done by expanding +\begin{definition}[\DescribeMacro\glsxtrlongnoshortdescname] +\cs{glsxtrlongnoshortdescname} +\end{definition} +(Similarly for the other +\texttt{long}\meta{modifier}\texttt{-noshort}\meta{modifier}\texttt{-desc} +styles, unless indicated otherwise.) This command should only be redefined before abbreviations +are defined, and any fragile or formatting commands within it need protecting. + +The \gloskey{description} must be provided by the user. The predefined +glossary styles won't display the short form. You can use the +post-description hook to automatically append the short form to the +description. The inline full form will display \meta{long} +(\meta{short}). + +\item[\abbrstyledef{long-desc}] A synonym for +\abbrstyle{long-noshort-desc}. + +\item[\abbrstyledef{long-noshort-sc-desc}] +Like the \abbrstyle{long-noshort-desc} style but the short form (accessed +through commands like \ics{glsxtrshort}) use \ics{glsabbrvscfont}. +(This style was originally called \depabbrstyle{long-desc-sc}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{long-noshort-sm-desc}] +Like \abbrstyle{long-noshort-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. +(This style was originally called \depabbrstyle{long-desc-sm}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{long-noshort-em-desc}] +Like \abbrstyle{long-noshort-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. The long form isn't emphasized. +(This style was originally called \depabbrstyle{long-desc-em}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{long-em-noshort-em-desc}] +New to version 1.04, like \abbrstyle{long-noshort-desc} but redefines +\cs{glsabbrvfont} to use \ics{glsabbrvemfont}. The long form uses +\ics{glsfirstlongemfont} and \ics{glslongemfont}. + +\item[\abbrstyledef{long-noshort}] +This style doesn't really make sense if you don't use the short +form anywhere in the document, but is provided for completeness. +This is like the \abbrstyle{long-noshort-desc} style, but +the \gloskey{sort} key is set to the short form. The \gloskey{name} +key is also set to the short form, but this is done by expanding +\begin{definition}[\DescribeMacro\glsxtrlongnoshortname] +\cs{glsxtrlongnoshortname} +\end{definition} +(Similarly for other +\texttt{long}\meta{modifier}\texttt{-noshort}\meta{modifier} styles, +unless indicated otherwise.) +This command should only be redefined before abbreviations are +defined, and fragile or formatting commands should be protected. + +The \gloskey{description} is set to the long form. + +\item[\abbrstyledef{long}] A synonym for \abbrstyle{long-noshort} + +\item[\abbrstyledef{long-noshort-sc}] +Like the \abbrstyle{long-noshort} style but the short form (accessed +through commands like \ics{glsxtrshort}) use \ics{glsabbrvscfont}. +(This style was originally called \depabbrstyle{long-sc}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{long-noshort-sm}] +Like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. +(This style was originally called \depabbrstyle{long-sm}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{long-noshort-em}] +This style is like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. The long form isn't emphasized. +(This style was originally called \depabbrstyle{long-em}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{long-em-noshort-em}] +New to version 1.04, this style is like \abbrstyle{long-noshort} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}, \cs{glsfirstlongfont} to use +\cs{glsfirstlongemfont} and \cs{glslongfont} to use +\cs{glslongemfont}. The short form isn't used by commands like +\ics{gls}, but can be obtained using \ics{glsxtrshort}. +The related style \abbrstyledef{long-em-noshort-em-noreg} +doesn't set the \catattr{regular} attribute. + +\end{description} + +\subsection{Predefined Abbreviation Styles that Don't Set the Regular +Attribute} +\label{sec:predefnonregabbrvstyles} + +The following abbreviation styles will set the +\catattr{regular} attribute to \qt{false} if it has previously +been set. If it hasn't already been set, it's left unset. +Other attributes may also be set, depending on the style. + +\begin{description} +\item[\abbrstyledef{long-short}] +On \gls{firstuse}, this style uses the format \meta{long} (\meta{short}). +The inline and display full forms are the same. The + \gloskey{sort} key is set to the short form. The \gloskey{name} is +also set to the short form through +\begin{definition}[\DescribeMacro\glsxtrlongshortname] +\cs{glsxtrlongshortname} +\end{definition} +(Similarly for other +\texttt{long}\meta{modifier}\texttt{-short}\meta{modifier} styles, +unless indicated otherwise.) +Any redefinition of this command must come before the abbreviations +are defined as it expands on definition. Make sure you protect +any commands that shouldn't be expanded. The long form can be +referenced with \cs{the}\cs{glslongtok} and the short form +can be referenced with \cs{the}\cs{glsshorttok}. + +The \gloskey{description} is set to the long form. The long and short +forms are separated by \cs{glsxtrfullsep}. If you want to insert +material within the parentheses (such as a~translation), try the +\abbrstyle{long-short-user} style. + +\item[\abbrstyledef{long-short-sc}] +Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. + +\item[\abbrstyledef{long-short-sm}] +Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. + +\item[\abbrstyledef{long-short-em}] +Like \abbrstyle{long-short} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + +\item[\abbrstyledef{long-em-short-em}] +New to version 1.04, this style is like \abbrstyle{long-short-em} but redefines \cs{glsfirstlongfont} to +use \ics{glsfirstlongemfont}. + +\item[\abbrstyledef{long-only-short-only}] +New to version 1.17, this style only shows the long form +on first use and only shows the short form on subsequent use. +The inline full form \cs{glsxtrfull} shows the long form +followed by the short form in parentheses. The \gloskey{name} +field is obtained from +\begin{definition}[\DescribeMacro\glsxtronlyname] +\cs{glsxtronlyname} +\end{definition} +Any redefinition of this command must come before the abbreviations +are defined as it expands on definition. Make sure you protect +any commands that shouldn't be expanded. The long form can be +referenced with \cs{the}\cs{glslongtok} and the short form +can be referenced with \cs{the}\cs{glsshorttok}. + +\item[\abbrstyledef{long-only-short-only-desc}] +New to version 1.17, this style is like +\abbrstyle{long-only-short-only} but the user must supply the +description. The \gloskey{name} +field is obtained from +\begin{definition}[\DescribeMacro\glsxtronlydescname] +\cs{glsxtronlydescname} +\end{definition} +Any redefinition of this command must come before the abbreviations +are defined as it expands on definition. Make sure you protect +any commands that shouldn't be expanded. The long form can be +referenced with \cs{the}\cs{glslongtok} and the short form +can be referenced with \cs{the}\cs{glsshorttok}. + +\item[\abbrstyledef{long-em-noshort-em-noreg}] +New to version 1.17, this style is like +\abbrstyle{long-em-noshort-em} but +doesn't set the \catattr{regular} attribute. + +\item[\abbrstyledef{long-short-user}] +This style was introduced in version 1.04. It's like the +\abbrstyle{long-short} style but additional information can be +inserted into the parenthetical material. This checks the value +of the field given by +\begin{definition}[\DescribeMacro\glsxtruserfield] +\cs{glsxtruserfield} +\end{definition} +(which defaults to \texttt{useri}) using \ics{ifglshasfield} +(provided by \styfmt{glossaries}). If the field hasn't been set, +the style behaves like the \abbrstyle{long-short} style and +produces \meta{long} (\meta{short}) but if the field has been set, +the contents of that field are inserted within the parentheses in +the form \meta{long} (\meta{short}, \meta{field-value}). +The format is governed by +\begin{definition}[\DescribeMacro\glsxtruserparen] +\cs{glsxtruserparen}\marg{text}\marg{label} +\end{definition} +where \meta{text} is the short form (for the +\abbrstyle{long-short-user} style) or the long form (for the +\abbrstyle{short-long-user} style). This command first inserts +a space using \cs{glsxtrfullsep} and then the parenthetical content +(using \ics{glsxtrparen}). +The \gloskey{description} is set to +\begin{definition}[\DescribeMacro\glsuserdescription] +\cs{glsuserdescription}\marg{long}\marg{label} +\end{definition} +The default definition ignores the \meta{label} and encapsulates +\meta{long} with \cs{glslonguserfont}. + +The \gloskey{name} is obtained by expanding +\cs{glsxtrlongshortname} (see above). +The \meta{text} argument includes the font formatting command, +\cs{glsfirstabbrvfont}\marg{short} in the case of the +\abbrstyle{long-short-user} style and +\cs{glsfirstlongfont}\marg{long} in the +case of the \abbrstyle{short-long-user} style. + +For example: +\begin{verbatim} +\setabbreviationstyle[acronym]{long-short-user} + +\newacronym{tug}{TUG}{\TeX\ User Group} + +\newacronym + [user1={German Speaking \TeX\ User Group}] + {dante}{DANTE}{Deutschsprachige Anwendervereinigung \TeX\ e.V} + +\end{verbatim} +On first use, \verb|\gls{tug}| will appear as: +\begin{quote} +\TeX\ User Group (TUG) +\end{quote} +whereas \verb|\gls{dante}| will appear as: +\begin{quote} +Deutschsprachige Anwendervereinigung \TeX\ e.V (DANTE, German Speaking \TeX\ User Group) +\end{quote} + +The short form is formatted according to +\begin{definition}[\DescribeMacro\glsabbrvuserfont] +\cs{glsabbrvuserfont}\marg{text} +\end{definition} +and the plural suffix is given by +\begin{definition}[\DescribeMacro\glsxtrusersuffix] +\cs{glsxtrusersuffix} +\end{definition} + +These may be redefined as appropriate. For example, +if you want a~smallcaps style, you can just set these commands +to those used by the \abbrstyle{long-short-sc} style: +\begin{verbatim} +\renewcommand{\glsabbruserfont}[1]{\glsabbrvscfont{#1}} +\renewcommand{\glsxtrusersuffix}{\glsxtrscsuffix} +\end{verbatim} + +\item[\abbrstyledef{long-noshort-noreg}] +This style is like \abbrstyle{long-noshort} but it doesn't +set the \catattr{regular} attribute. + +\item[\abbrstyledef{long-noshort-desc-noreg}] +This style is like \abbrstyle{long-noshort-desc} but it doesn't +set the \catattr{regular} attribute. + +\item[\abbrstyledef{long-short-desc}] +On \gls{firstuse}, this style uses the format \meta{long} (\meta{short}). +The inline and display full forms are the same. The \gloskey{name} +is set to the full form. The \gloskey{sort} key is set to +\meta{long} (\meta{short}). Before version 1.04, this was +incorrectly set to the short form. If you want to revert back to +this you can redefine +\begin{definition}[\DescribeMacro\glsxtrlongshortdescsort] +\cs{glsxtrlongshortdescsort} +\end{definition} +For example: +\begin{verbatim} +\renewcommand*{\glsxtrlongshortdescsort}{\the\glsshorttok} +\end{verbatim} +The \gloskey{description} must be supplied by the user. +The long and short forms are separated by \cs{glsxtrfullsep}. The \gloskey{name} +field is obtained from +\begin{definition}[\DescribeMacro\glsxtrlongshortdescname] +\cs{glsxtrlongshortdescname} +\end{definition} +(Similarly for other +\texttt{long}\meta{modifier}\texttt{-short}\meta{modifier}\texttt{-desc} +styles, unless indicated otherwise.) +Any redefinition of this command must come before the abbreviations +are defined as it expands on definition. Make sure you protect +any commands that shouldn't be expanded. The long form can be +referenced with \cs{the}\cs{glslongtok} and the short form +can be referenced with \cs{the}\cs{glsshorttok}. + +\item[\abbrstyledef{long-short-sc-desc}] +Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. + +\item[\abbrstyledef{long-short-sm-desc}] +Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. + +\item[\abbrstyledef{long-short-em-desc}] +Like \abbrstyle{long-short-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + +\item[\abbrstyledef{long-em-short-em-desc}] +New to version 1.04, this style is like \abbrstyle{long-short-em-desc} but redefines \cs{glsfirstlongfont} to +use \ics{glsfirstlongemfont}. + +\item[\abbrstyledef{long-em-noshort-em-desc-noreg}] +New to version 1.17, this style is like +\abbrstyle{long-em-noshort-em-desc} but +doesn't set the \catattr{regular} attribute. + + +\item[\abbrstyledef{long-short-user-desc}] +New to version 1.04, this style is like a~cross between the +\abbrstyle{long-short-desc} style and the +\abbrstyle{long-short-user} style. The display and inline forms are +as for \abbrstyle{long-short-user} and the \gloskey{name} key is +obtained from +\begin{definition}[\DescribeMacro\glsxtrlongshortuserdescname] +\cs{glsxtrlongshortuserdescname} +\end{definition} +Again, this should only be redefined before \cs{newabbreviation} (or +\cs{newacronym}), and fragile and formatting commands need protecting. + +The \gloskey{description} key must be +supplied in the optional argument of \cs{newabbreviation} +(or \cs{newacronym}). The \gloskey{sort} key is set to \meta{long} +(\meta{short}) as per the \abbrstyle{long-short-desc} style. + +\item[\abbrstyledef{short-nolong-noreg}] +This is like \abbrstyle{short-nolong} but doesn't set the +\catattr{regular} attribute. + +\item[\abbrstyledef{nolong-short-noreg}] +This is like \abbrstyle{nolong-short} but doesn't set the +\catattr{regular} attribute. + +\item[\abbrstyledef{short-long}] +On \gls{firstuse}, this style uses the format \meta{short} (\meta{long}). +The inline and display full forms are the same. The \gloskey{name} +and \gloskey{sort} keys are set to the short form. The +\gloskey{description} is set to the long form. +The short and long forms are separated by \cs{glsxtrfullsep}. +If you want to insert +material within the parentheses (such as a~translation), try the +\abbrstyle{short-long-user} style. + +The \gloskey{name} field is obtained from +\begin{definition}[\DescribeMacro\glsxtrshortlongname] +\cs{glsxtrshortlongname} +\end{definition} +(Similarly for other +\texttt{short}\meta{modifier}\texttt{-long}\meta{modifier} styles, +unless indicated otherwise.) +Any redefinition of this command must come before the abbreviations +are defined as it expands on definition. Make sure you protect +any commands that shouldn't be expanded. The long form can be +referenced with \cs{the}\cs{glslongtok} and the short form +can be referenced with \cs{the}\cs{glsshorttok}. + + +\item[\abbrstyledef{short-sc-long}] +Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. + +\item[\abbrstyledef{short-sm-long}] +Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. + +\item[\abbrstyledef{short-em-long}] +Like \abbrstyle{short-long} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + +\item[\abbrstyledef{short-em-long-em}] +New to version 1.04, this style is like \abbrstyle{short-em-long} but redefines \cs{glsfirstlongfont} to +use \ics{glsfirstlongemfont}. + +\item[\abbrstyledef{short-long-user}] +New to version 1.04. This style is like the +\abbrstyle{long-short-user} style but with the long and short forms +switched. The parenthetical material is governed by the same command +\ics{glsxtruserparen}, but the first argument supplied to it is +the long form instead of the short form. The \gloskey{name} field is +obtained by expanding +\begin{definition}[\DescribeMacro\glsxtrshortlongname] +\cs{glsxtrshortlongname} +\end{definition} +Again, this should only be redefined before \cs{newabbreviation} (or +\cs{newacronym}) and commands that should be expanded need to be +protected. The \gloskey{description} is set to +\cs{glsuserdescription}\marg{long}\marg{label}. + +\item[\abbrstyledef{short-nolong-desc-noreg}] +This style is like \abbrstyle{short-nolong-desc} but it doesn't +set the \catattr{regular} attribute. + +\item[\abbrstyledef{short-long-desc}] +On \gls{firstuse}, this style uses the format \meta{short} (\meta{long}). +The inline and display full forms are the same. The \gloskey{name} +is set to the full form. The +\gloskey{description} must be supplied by the user. +The short and long forms are separated by \cs{glsxtrfullsep}. The \gloskey{name} +field is obtained from +\begin{definition}[\DescribeMacro\glsxtrshortlongdescname] +\cs{glsxtrshortlongdescname} +\end{definition} +(Similarly for other +\texttt{short}\meta{modifier}\texttt{-long}\meta{modifier}\texttt{-desc} +styles, unless indicated otherwise.) +Any redefinition of this command must come before the abbreviations +are defined as it expands on definition. Make sure you protect +any commands that shouldn't be expanded. The long form can be +referenced with \cs{the}\cs{glslongtok} and the short form +can be referenced with \cs{the}\cs{glsshorttok}. + +\item[\abbrstyledef{short-sc-long-desc}] +Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. + +\item[\abbrstyledef{short-sm-long-desc}] +Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. + +\item[\abbrstyledef{short-em-long-desc}] +Like \abbrstyle{short-long-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + +\item[\abbrstyledef{short-em-long-em-desc}] +New to version 1.04, this style is like \abbrstyle{short-em-long-desc} but redefines \cs{glsfirstlongfont} to +use \ics{glsfirstlongemfont}. + +\item[\abbrstyledef{short-long-user-desc}] +New to version 1.04, this style is like a~cross between the +\abbrstyle{short-long-desc} style and the +\abbrstyle{short-long-user} style. The display and inline forms are +as for \abbrstyle{short-long-user}, but the \gloskey{name} key is +obtained from +\begin{definition}[\DescribeMacro\glsxtrshortlonguserdescname] +\cs{glsxtrshortlonguserdescname} +\end{definition} +Again, this should only be redefined before \cs{newabbreviation} (or +\cs{newacronym}), and fragile and formatting commands need protecting. + +The \gloskey{description} key must be +supplied in the optional argument of \cs{newabbreviation} +(or \cs{newacronym}). + +\item[\abbrstyledef{short-footnote}] +On \gls{firstuse}, this style displays the short form with the long form +as a footnote. This style automatically sets the +\catattr{nohyperfirst} attribute to \qt{true} for the supplied +category, so the \gls{firstuse} won't be hyperlinked (but the footnote +marker may be, if the \sty{hyperref} package is used). + +The inline full form uses the \meta{short} +(\meta{long}) style. The \gloskey{name} is set to the short form. +The \gloskey{description} is set to the long form. The +\gloskey{name} key is obtained by expanding +\begin{definition}[\DescribeMacro\glsxtrfootnotename] +\cs{glsxtrfootnotename} +\end{definition} +(Similarly for other +\texttt{short\meta{modifier}-\meta{modifier}footnote} styles, unless +indicated otherwise.) Again, this command should only be redefined +before \cs{newabbreviation} (or \cs{newacronym}), and fragile or +formatting commands should be protected from expansion. + +As from version 1.05, all the footnote styles use: +\begin{definition}[\DescribeMacro\glsfirstlongfootnotefont] +\cs{glsfirstlongfootnotefont}\marg{text} +\end{definition} +to format the long form on \gls{firstuse} or for the full form and +\begin{definition}[\DescribeMacro\glslongfootnotefont] +\cs{glslongfootnotefont}\marg{text} +\end{definition} +to format the long form elsewhere (for example, when used with +\cs{glsxtrlong}). + +As from version 1.07, all the footnote styles use: +\begin{definition}[\DescribeMacro\glsxtrabbrvfootnote] +\cs{glsxtrabbrvfootnote}\marg{label}\marg{long} +\end{definition} +By default, this just does \ics{footnote}\marg{long} (the first +argument is ignored). For example, to make the footnote text +link to the relevant place in the glossary: +\begin{verbatim} +\renewcommand{\glsxtrabbrvfootnote}[2]{% + \footnote{\glshyperlink[#2]{#1}}% +} +\end{verbatim} +or to include the short form with a hyperlink: +\begin{verbatim} +\renewcommand{\glsxtrabbrvfootnote}[2]{% + \footnote{\glshyperlink[\glsfmtshort{#1}]{#1}: #2}% +} +\end{verbatim} +Note that I haven't used commands like \cs{glsxtrshort} to +avoid interference (see \sectionref{sec:entryfmtmods} +and \sectionref{sec:nested}). + +\item[\abbrstyledef{footnote}] A synonym for +\abbrstyle{short-footnote}. + +\item[\abbrstyledef{short-sc-footnote}] +Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. +(This style was originally called \depabbrstyle{footnote-sc}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{short-sc-footnote}] +Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. +(This style was originally called \depabbrstyle{footnote-sm}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{short-em-footnote}] +Like \abbrstyle{short-footnote} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. +(This style was originally called \depabbrstyle{footnote-em}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{short-postfootnote}] +This is similar to the \abbrstyle{short-footnote} style but doesn't modify +the category attribute. Instead it changes \postlinkcat\ to +insert the footnote after the +\gls{linktext} on \gls{firstuse}. This will also defer the footnote until after any +following punctuation character that's recognised by +\ics{glsxtrifnextpunc}. + +The inline full form uses the \meta{short} +(\meta{long}) style. The \gloskey{name} is set to the short form. +The \gloskey{description} is set to the long form. +Note that this style will change \cs{glsxtrfull} (and its variants) +so that it fakes non-\gls{firstuse}. (Otherwise the footnote would +appear after the inline form.) + +\item[\abbrstyledef{postfootnote}] A synonym for +\abbrstyle{short-postfootnote}. + +\item[\abbrstyledef{short-sc-postfootnote}] +Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. +(This style was originally called \depabbrstyle{postfootnote-sc}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{short-sm-postfootnote}] +Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. +(This style was originally called \depabbrstyle{postfootnote-sm}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{short-em-postfootnote}] +Like \abbrstyle{short-postfootnote} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. +(This style was originally called \depabbrstyle{postfootnote-em}. Renamed in version +1.04, but original name retained as a deprecated synonym for +backward-compatibility.) + +\item[\abbrstyledef{short-postlong-user}] +This style was introduced in version 1.12. It's like the +\abbrstyle{short-long-user} style but defers the parenthetical +material to after the link-text. This means that you don't have such +a long hyperlink (which can cause problems for the DVI \LaTeX\ format) +and it also means that the user supplied material can include a +hyperlink to another location. The \gloskey{name} key is obtained +from \cs{glsxtrshortlongname}. + +\item[\abbrstyledef{short-postlong-user-desc}] +This style was introduced in version 1.12. It's like the above +\abbrstyle{short-postlong-user} style but the \gloskey{description} +must be specified. The \gloskey{name} is obtained from +\cs{glsxtrshortlonguserdescname}. + +\item[\abbrstyledef{long-postshort-user}] +This style was introduced in version 1.12. It's like the above +\abbrstyle{short-postlong-user} style but the long form is shown +first and the short form is in the parenthetical material (as for +\abbrstyle{long-short-user}) style. + +\item[\abbrstyledef{long-postshort-user-desc}] +This style was introduced in version 1.12. It's like the above +\abbrstyle{long-postshort-user} style but the \gloskey{description} +must be specified. The \gloskey{name} is obtained from +\cs{glsxtrlongshortuserdescname}. + +\item[\abbrstyledef{long-hyphen-short-hyphen}] +This style (new to v1.17) is designed to work with the \catattr{markwords} +category attribute. The full form is formatted using +\begin{definition}[\DescribeMacro\glsxtrlonghyphenshort] +\cs{glsxtrlonghyphenshort}\marg{label}\marg{long}\marg{short}\marg{insert} +\end{definition} +where \meta{insert} is the inserted material +provided in the final optional argument of commands like +\cs{insert}. If \meta{insert} start with a hyphen, then this +locally redefines \ics{glsxtrwordsep} to a hyphen, which means that +if the \catattr{markwords} attribute is set then the long form +will become hyphenated. (If this attribute isn't set, there's +no alteration to the way the long form is displayed.) +The \gloskey{name} key is obtained from \cs{glsxtrlongshortname}. + +Unlike the other \meta{long} (\meta{short}) type of styles, +such as \abbrstyle{long-short}, this style +also repeats the insertion in the parenthetical part, so that the +first use form is: +\begin{quote} +\cs{glsfirstlonghyphenfont}\marg{long}\meta{insert} +(\cs{glsfirstabbrvhyphenfont}\marg{short}\meta{insert}) +\end{quote} +The space before the parenthetical material is actually given by +\cs{glsxtrfullsep}\marg{label} which defaults to a space. +The \meta{insert} may be moved into the formatting commands +according to the conditional \cs{ifglsxtrinsertinside}. + +For example, if \texttt{ip} is defined using: +\begin{verbatim} +\glssetcategoryattribute{english}{markwords}{true} +\setabbreviationstyle[english]{long-hyphen-short-hyphen} +\newabbreviation[category=english]{ip}{IP}{Internet Protocol} +\end{verbatim} +then +\begin{verbatim} +\gls{ip}[-Adressen] +\end{verbatim} +will do +\begin{quote} +Internet-Protocol-Adressen (IP-Adressen) +\end{quote} +on first use, whereas +\begin{verbatim} +\gls{ip}[ Address] +\end{verbatim} +will do +\begin{quote} +Internet Protocol Address (IP Address) +\end{quote} +on first use. + +\begin{important} +Note that the hyphenation isn't applied when using commands like +\cs{glsxtrlong}. This means that +\begin{verbatim} +\glsxtrlong{ip}[-Adressen] +\end{verbatim} +will do +\begin{quote} +Internet Protocol-Adressen +\end{quote} +\end{important} + +If the \catattr{markwords} attribute hadn't been set, then the +first use of +\begin{verbatim} +\gls{ip}[-Adressen] +\end{verbatim} +would do +\begin{quote} +Internet Protocol-Adressen (IP-Adressen) +\end{quote} +instead. + +\begin{important} +If the inserted material \meta{insert} is likely to contain commands like +\cs{gls}, then use \abbrstyle{long-hyphen-postshort-hyphen} +instead to avoid nested links. +\end{important} + +If you want the short version in small-caps, you can +just redefine \cs{glsabbrvhyphenfont} and \cs{glsxtrhyphensuffix} +to use the small-caps versions. For example: +\begin{verbatim} +\renewcommand{\glsabbrvhyphenfont}{\glsabbrvscfont} +\renewcommand{\glsxtrhyphensuffix}{\glsxtrscsuffix} +\end{verbatim} +Similarly for other font-changing variations. + +\item[\abbrstyledef{long-hyphen-noshort-desc-noreg}] +New to version 1.17, this style is like +\abbrstyle{long-hyphen-short-hyphen-desc} except that the +parenthetical part is omitted and the long form is displayed +on subsequent use. The short form can be accessed +with \cs{glsxtrshort} but just uses the default abbreviation font. +There's no regular version of this style as the regular form +doesn't have the flexibility to deal with the hyphen switch. +The \gloskey{name} is obtained from \cs{glsxtrlongnoshortdescname}. + +\item[\abbrstyledef{long-hyphen-noshort-noreg}] +New to version 1.17, this style is like +\abbrstyle{long-hyphen-noshort-desc-noreg} but the +name is set to the short form and the description is set to the long +form. + +\item[\abbrstyledef{long-hyphen-short-hyphen-desc}] + +New to version 1.17. +This is similar to \abbrstyle{long-hyphen-short-hyphen} but the user +supplies the description. The \gloskey{name} is obtained from +\cs{glsxtrlongshortdescname}. + +\item[\abbrstyledef{long-hyphen-postshort-hyphen}] + +New to version 1.17. +This is similar to \abbrstyle{long-hyphen-short-hyphen} but the +inserted and parenthetical material are moved to the post-link hook. +On first use, \cs{gls}\marg{label}\oarg{insert} will do +\begin{display} +\cs{glsxtrlonghyphen}\marg{long}\marg{label}\marg{insert}\cs{glsxtrposthyphenshort}\marg{label}\meta{insert} +\end{display} +where +\begin{definition}[\DescribeMacro\glsxtrposthyphenshort] +\cs{glsxtrposthyphenshort}\marg{label}\meta{insert} +\end{definition} +is in the post-link hook. This uses the format: +\begin{display} +\meta{insert} (\cs{glsfirstabbrvhyphenfont}\marg{short}\meta{isnert}) +\end{display} + +\begin{important} +The singular short form is always used here, even with \cs{glspl}. +(Unlike \abbrstyle{long-hyphen-long-hyphen}.) +\end{important} + +The part in the link-text on first use: +\begin{definition}[\DescribeMacro\glsxtrlonghyphen] +\cs{glsxtrlonghyphen}\marg{long}\marg{label}\marg{insert} +\end{definition} +checks if \meta{insert} starts with a hyphen. If it does, then +\cs{glsxtrwordsep} is locally redefined to a hyphen. This command +only uses \meta{insert} to test if it starts with a hyphen. +The actual insertion code isn't typeset until the post-link +hook and it's also localised, which means that you can use +commands like \cs{gls} in \meta{insert} for this style without +causing nested hyperlinks, but only for commands like \cs{gls}. + +\begin{important} +Don't use \cs{gls} in the \meta{insert} part for commands +like \cs{glsxtrfull}, \cs{glsxtrshort} or \cs{glsxtrlong}. +\end{important} + +The inline full display format used by commands like \cs{glsxtrfull} +behaves differently to the first use of \cs{gls} with this style. +It's better to use \cs{glsreset}\marg{label}\cs{gls}\marg{label} +if you want to ensure the full format. + +\item[\abbrstyledef{long-hyphen-postshort-hyphen-desc}] + +New to version 1.17. +This is similar to \abbrstyle{long-hyphen-postshort-hyphen} but the +user supplies the description. The \gloskey{name} is obtained from +\cs{glsxtrlongshortdescname}. + + +\item[\abbrstyledef{short-hyphen-long-hyphen}] +This style (new to v1.17) is like +\abbrstyle{long-hyphen-short-hyphen}, except that the short form +is displayed first followed by the long form in parentheses. The full form is formatted using +\begin{definition}[\DescribeMacro\glsxtrshorthyphenlong] +\cs{glsxtrshorthyphenlong}\marg{label}\marg{short}\marg{long}\marg{insert} +\end{definition} +which behaves in an analogous way to \cs{glsxtrlonghyphenshort}. +The \gloskey{name} is obtained from \cs{glsxtrshortlongname}. + +\item[\abbrstyledef{short-hyphen-long-hyphen-desc}] + +New to version 1.17. +This is similar to \abbrstyle{short-hyphen-long-hyphen} but the +user supplies the description. +The \gloskey{name} is obtained from \cs{glsxtrshortlongdescname}. + +\item[\abbrstyledef{short-hyphen-postlong-hyphen}] +This style (new to v1.17) is like +\abbrstyle{long-hyphen-postshort-hyphen}, but the +short form is displayed first followed by the long form in +parentheses. +On first use, \cs{gls}\marg{label}\oarg{insert} will do +\begin{display} +\cs{glsxtrshorthyphen}\marg{short}\marg{label}\marg{insert}\cs{glsxtrposthyphenlong}\marg{label}\meta{insert} +\end{display} +where +\begin{definition}[\DescribeMacro\glsxtrposthyphenlong] +\cs{glsxtrposthyphenlong}\marg{label}\meta{insert} +\end{definition} +is in the post-link hook. These commands behave in an analogous +manner to those used with \abbrstyle{long-hyphen-postshort-hyphen}. +The \gloskey{name} is obtained from \cs{glsxtrshortlongname}. + +\begin{important} +Don't use \cs{gls} in the \meta{insert} part for commands +like \cs{glsxtrfull}, \cs{glsxtrshort} or \cs{glsxtrlong}. +\end{important} + +The inline full display format used by commands like \cs{glsxtrfull} +behaves differently to the first use of \cs{gls} with this style. +It's better to use \cs{glsreset}\marg{label}\cs{gls}\marg{label} +if you want to ensure the full format. + +\item[\abbrstyledef{short-hyphen-postlong-hyphen-desc}] + +New to version 1.17. +This is similar to \abbrstyle{short-hyphen-postlong-hyphen} but the +user supplies the description. The \gloskey{name} is obtained from +\cs{glsxtrshortlongdescname}. + +\end{description} + +\section{Defining New Abbreviation Styles} +\label{sec:newabbrvstyle} + +New abbreviation styles may be defined using: +\begin{definition}[\DescribeMacro\newabbreviationstyle] +\cs{newabbreviationstyle}\marg{name}\marg{setup}\marg{fmts} +\end{definition} +\begin{sloppypar}\noindent +where \meta{name} is the name of the new style (as used in the +mandatory argument of \ics{setabbreviationstyle}). This is similar +but not identical to the \styfmt{glossaries} package's +\ics{newacronymstyle} command. +\end{sloppypar} + +\begin{important} +You can't use styles defined by +\cs{newacronymstyle} with \styfmt{glossaries-extra} unless you have +reverted \ics{newacronym} back to its generic definition from \styfmt{glossaries} +(using \ics{RestoreAcronyms}). The acronym styles from the +\styfmt{glossaries} package can't be used with abbreviations defined +with \cs{newabbreviation}. +\end{important} + +The \meta{setup} argument deals with the way the entry is defined +and may set attributes for the given abbreviation +category. This argument should redefine +\begin{definition}[\DescribeMacro\CustomAbbreviationFields] +\cs{CustomAbbreviationFields} +\end{definition} +to set the entry fields including the \gloskey{name} (defaults to +the short form if omitted), +\gloskey{sort}, \gloskey{first}, \gloskey{firstplural}. Other fields +may also be set, such as \gloskey{text}, \gloskey{plural} and +\gloskey{description}. + +\begin{important} +\cs{CustomAbbreviationFields} is expanded by \cs{newabbreviation} +so take care to protect commands that shouldn't be expanded. +\end{important} + +For example, the \abbrstyle{long-short} style has the following in +\meta{setup}: +\begin{verbatim} + \renewcommand*{\CustomAbbreviationFields}{% + name={\protect\glsabbrvfont{\the\glsshorttok}}, + sort={\the\glsshorttok}, + first={\protect\glsfirstlongfont{\the\glslongtok}% + \protect\glsxtrfullsep{\the\glslabeltok}% + \glsxtrparen{\protect\glsfirstabbrvfont{\the\glsshorttok}}},% + firstplural={\protect\glsfirstlongfont{\the\glslongpltok}% + \protect\glsxtrfullsep{\the\glslabeltok}% + \glsxtrparen{\protect\glsfirstabbrvfont{\the\glsshortpltok}}},% + plural={\protect\glsabbrvfont{\the\glsshortpltok}},% + description={\the\glslongtok}}% +\end{verbatim} +Note that the \gloskey{first} and \gloskey{firstplural} are +set even though they're not used by \cs{gls}. + +The basic styles, such as \abbrstyle{long-short}, use commands like +\cs{glsabbrvfont} (which are redefined whenever the style formatting +is set) within \cs{CustomAbbreviationFields}. Other styles, such as +\abbrstyle{long-em-short-em} directly use their own custom commands, +such as \cs{glsabbrvemfont}. With these styles, commands like +\cs{glsabbrvfont} still need to be defined as appropriate in the +\meta{fmts} argument even if they're not used within +\cs{CustomAbbreviationFields}. + +The \meta{setup} argument may also redefine +\begin{definition}[\DescribeMacro\GlsXtrPostNewAbbreviation] +\cs{GlsXtrPostNewAbbreviation} +\end{definition} +which can be used to assign attributes. (This will automatically +be initialised to do nothing.) + +For example, the \abbrstyle{short-footnote} includes the following in +\meta{setup}: +\begin{verbatim} + \renewcommand*{\GlsXtrPostNewAbbreviation}{% + \glssetattribute{\the\glslabeltok}{nohyperfirst}{true}% + \glshasattribute{\the\glslabeltok}{regular}% + {% + \glssetattribute{\the\glslabeltok}{regular}{false}% + }% + {}% + }% +\end{verbatim} +This sets the \catattr{nohyperfirst} attribute to \qt{true}. +It also unsets the \catattr{regular} attribute if it has +previously been set. Note that the \catattr{nohyperfirst} +attribute doesn't get unset by other styles, so take care +not to switch styles for the same category. + +You can access the short, long, short plural and long plural +values through the following token registers. + +Short value (defined by \styfmt{glossaries}): +\begin{definition}[\DescribeMacro\glsshorttok] +\cs{glsshorttok} +\end{definition} + +Short plural value (defined by \styfmt{glossaries-extra}): +\begin{definition}[\DescribeMacro\glsshortpltok] +\cs{glsshortpltok} +\end{definition} +(This may be the default value or, if provided, the value provided by the user +through the \gloskey{shortplural} key in the optional argument +of \ics{newabbreviation}.) + +Long value (defined by \styfmt{glossaries}): +\begin{definition}[\DescribeMacro\glslongtok] +\cs{glslongtok} +\end{definition} + +Long plural value (defined by \styfmt{glossaries-extra}): +\begin{definition}[\DescribeMacro\glslongpltok] +\cs{glslongpltok} +\end{definition} +(This may be the default value or, if provided, the value provided by the user +through the \gloskey{longplural} key in the optional argument +of \ics{newabbreviation}.) + +The short or long values may be modified by attributes (such as +\catattr{markwords}). The above registers reflect the modification. +If you want to access the original (unmodified) short or long form +(as provided in the final two arguments of \cs{newabbreviation}), +then use the commands: +\begin{definition}[\DescribeMacro\glsxtrorgshort] +\cs{glsxtrorgshort} +\end{definition} +for the short form and +\begin{definition}[\DescribeMacro\glsxtrorglong] +\cs{glsxtrorglong} +\end{definition} +for the long form. (These may be useful for the \gloskey{sort} key +to avoid any formatting that may be added by the attribute setting.) + +There are two other registers available that are defined by +\styfmt{glossaries}: + +\begin{definition}[\DescribeMacro\glslabeltok] +\cs{glslabeltok} +\end{definition} +which contains the entry's label and +\begin{definition}[\DescribeMacro\glskeylisttok] +\cs{glskeylisttok} +\end{definition} +which contains the values provided in the optional argument +of \ics{newabbreviation}. + +Remember put \cs{the} in front of the register command as in the +examples above. The category label can be access through +the command (not a register): +\begin{definition}[\DescribeMacro\glscategorylabel] +\cs{glscategorylabel} +\end{definition} +This may be used inside the definition of +\cs{GlsXtrPostNewAbbreviation}. + +If you want to base a style on an existing style, you can use +\begin{definition}[\DescribeMacro\GlsXtrUseAbbrStyleSetup] +\cs{GlsXtrUseAbbrStyleSetup}\marg{name} +\end{definition} +where \meta{name} is the name of the existing style. +For example, the \abbrstyle{long-noshort-sc-desc} style simply does +\begin{verbatim} +\GlsXtrUseAbbrStyleSetup{long-noshort-desc} +\end{verbatim} +within \meta{setup}. + +The \meta{fmts} argument deals with the way the entry is displayed +in the document. This argument should redefine the following +commands. + +The default suffix for the plural short form (if not overridden by +the \gloskey{shortplural} key): +\begin{definition}[\DescribeMacro\abbrvpluralsuffix] +\cs{abbrvpluralsuffix} +\end{definition} +(Note that this isn't used for the plural long form, which +just uses the regular \cs{glspluralsuffix}.) + +The font used for the short form on \gls{firstuse} or in the full forms: +\begin{definition}[\DescribeMacro\glsfirstabbrvfont] +\cs{glsfirstabbrvfont}\marg{text} +\end{definition} + +The font used for the short form on subsequent use or through +commands like \ics{glsxtrshort}: +\begin{definition}[\DescribeMacro\glsabbrvfont] +\cs{glsabbrvfont}\marg{text} +\end{definition} + +The font used for the long form on \gls{firstuse} or in the full forms: +\begin{definition}[\DescribeMacro\glsfirstlongfont] +\cs{glsfirstlongfont}\marg{text} +\end{definition} + +The font used for the long form in commands like \cs{glsxtrlong} +use: +\begin{definition}[\DescribeMacro\glslongfont] +\cs{glslongfont}\marg{text} +\end{definition} + +Display full form singular no case-change (used by \ics{gls} on +\gls{firstuse} for abbreviations without the \catattr{regular} attribute +set): +\begin{definition}[\DescribeMacro\glsxtrfullformat] +\cs{glsxtrfullformat}\marg{label}\marg{insert} +\end{definition} + +Display full form singular first letter converted to upper case +(used by \ics{Gls} on \gls{firstuse} for abbreviations without the +\catattr{regular} attribute set): +\begin{definition}[\DescribeMacro\Glsxtrfullformat] +\cs{Glsxtrfullformat}\marg{label}\marg{insert} +\end{definition} + +Display full form plural no case-change +(used by \ics{glspl} on \gls{firstuse} for abbreviations without the +\catattr{regular} attribute set): +\begin{definition}[\DescribeMacro\glsxtrfullplformat] +\cs{glsxtrfullplformat}\marg{label}\marg{insert} +\end{definition} + +Display full form plural first letter converted to upper case +(used by \ics{Glspl} on \gls{firstuse} for abbreviations without the +\catattr{regular} attribute set): +\begin{definition}[\DescribeMacro\Glsxtrfullplformat] +\cs{Glsxtrfullplformat}\marg{label}\marg{insert} +\end{definition} + +In addition \meta{fmts} may also redefine the following commands that +govern the inline full formats. If the style doesn't redefine them, +they will default to the same as the display full forms. + +Inline singular no case-change (used by +\ics{glsentryfull}, \ics{glsxtrfull} and \ics{GLSxtrfull}): +\begin{definition}[\DescribeMacro\glsxtrinlinefullformat] +\cs{glsxtrinlinefullformat}\marg{label}\marg{insert} +\end{definition} + +Inline singular first letter converted to upper case (used by +\ics{Glsentryfull} and \ics{Glsxtrfull}): +\begin{definition}[\DescribeMacro\Glsxtrinlinefullformat] +\cs{Glsxtrinlinefullformat}\marg{label}\marg{insert} +\end{definition} + +Inline plural no case-change (used by +\ics{glsentryfullpl}, \ics{glsxtrfullpl} and \ics{GLSxtrfullpl}): +\begin{definition}[\DescribeMacro\glsxtrinlinefullplformat] +\cs{glsxtrinlinefullplformat}\marg{label}\marg{insert} +\end{definition} + +Inline plural first letter converted to upper case (used by +\ics{Glsentryfullpl} and \ics{Glsxtrfullpl}): +\begin{definition}[\DescribeMacro\Glsxtrinlinefullplformat] +\cs{Glsxtrinlinefullplformat}\marg{label}\marg{insert} +\end{definition} + +(New to version 1.17.) +You can also modify the way the subsequent use is formatted by +redefining the following four commands, but these won't be used for +abbreviations with the \catattr{regular} attribute set. If the style +doesn't redefine these commands, the default values are used. + +Singular with no case-change: +\begin{definition}[\DescribeMacro\glsxtrsubsequentfmt] +\cs{glsxtrsubsequentfmt}\marg{label}\marg{insert} +\end{definition} + +Singular with first letter upper case: +\begin{definition}[\DescribeMacro\Glsxtrsubsequentfmt] +\cs{Glsxtrsubsequentfmt}\marg{label}\marg{insert} +\end{definition} + +Plural with no case-change: +\begin{definition}[\DescribeMacro\glsxtrsubsequentplfmt] +\cs{glsxtrsubsequentplfmt}\marg{label}\marg{insert} +\end{definition} + +Plural with first letter upper case: +\begin{definition}[\DescribeMacro\Glsxtrsubsequentplfmt] +\cs{Glsxtrsubsequentplfmt}\marg{label}\marg{insert} +\end{definition} + +If you want to provide support for \sty{glossaries-accsupp} +use the following \cs{glsaccess\meta{xxx}} commands +(\sectionref{sec:accsupp}) within the definitions of +\cs{glsxtrfullformat} etc instead of the analogous +\cs{glsentry}\meta{xxx} commands. (If you don't use +\sty{glossaries-accsupp}, they will just do the corresponding +\cs{glsentry}\meta{xxx} command.) + +For example, the \abbrstyle{short-long} style has the following in +\meta{fmts}: +\begin{verbatim} + \renewcommand*{\abbrvpluralsuffix}{\glsxtrabbrvpluralsuffix}% + \renewcommand*{\glsabbrvfont}[1]{\glsabbrvdefaultfont{##1}}% + \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvdefaultfont{##1}}% + \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% + \renewcommand*{\glslongfont}[1]{\glslongdefaultfont{##1}}% + \renewcommand*{\glsxtrfullformat}[2]{% + \glsfirstabbrvfont{\glsaccessshort{##1}\ifglsxtrinsertinside##2\fi}% + \ifglsxtrinsertinside\else##2\fi + \glsxtrfullsep{##1}% + \glsxtrparen{\glsfirstlongfont{\glsaccesslong{##1}}}% + }% + \renewcommand*{\glsxtrfullplformat}[2]{% + \glsfirstabbrvfont{\glsaccessshortpl{##1}\ifglsxtrinsertinside##2\fi}% + \ifglsxtrinsertinside\else##2\fi + \glsxtrfullsep{##1}% + \glsxtrparen{\glsfirstlongfont{\glsaccesslongpl{##1}}}% + }% + \renewcommand*{\Glsxtrfullformat}[2]{% + \glsfirstabbrvfont{\Glsaccessshort{##1}\ifglsxtrinsertinside##2\fi}% + \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}% + \glsxtrparen{\glsfirstlongfont{\glsaccesslong{##1}}}% + }% + \renewcommand*{\Glsxtrfullplformat}[2]{% + \glsfirstabbrvfont{\Glsaccessshortpl{##1}\ifglsxtrinsertinside##2\fi}% + \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}% + \glsxtrparen{\glsfirstlongfont{\glsaccesslongpl{##1}}}% + }% +\end{verbatim} +Since the inline full commands aren't redefined, they default +to the same as the display versions. + +If you want to base a style on an existing style, you can use +\begin{definition}[\DescribeMacro\GlsXtrUseAbbrStyleFmts] +\cs{GlsXtrUseAbbrStyleFmts}\marg{name} +\end{definition} +within \meta{fmts}, where \meta{name} is the name of the existing +style. For example, the \abbrstyle{long-short-desc} style has the +following in \meta{fmts}: +\begin{verbatim} + \GlsXtrUseAbbrStyleFmts{long-short}% +\end{verbatim} + +Here's an example of an abbreviation style that's based on +\abbrstyle{long-short} that displays the short form within +\cs{textsf}: +\begin{verbatim} +\newabbreviationstyle +{custom-sf}% label +{% setup + \GlsXtrUseAbbrStyleSetup{short-long}% +}% +{% fmts + \GlsXtrUseAbbrStyleFmts{short-long}% + \renewcommand*{\glsabbrvfont}[1]{\textsf{##1}}% +} +\end{verbatim} +Note that this wouldn't work if it was instead based on one of the +modified versions such as \abbrstyle{short-sc-long} as they +explicitly use their own formatting commands, such as +\cs{glsabbrvemfont}. The base styles, such as \abbrstyle{short-long}, +use the more generic \cs{glsabbrvfont} etc which makes them easier +to adapt than the modified styles. + +For further details, see the \qt{Abbreviations} section in the documented code +(\texttt{glossaries-extra-code.pdf}). + +\chapter{Entries in Sectioning Titles, Headers, Captions and Contents} +\label{sec:headtitle} + +The \styfmt{glossaries} user manual cautions against using commands +like \cs{gls} in chapter or section titles. The principle problems +are: +\begin{itemize} +\item if you have a table of contents, the \gls{firstuseflag} +will be unset in the contents rather than later in the document; +\item if you have the location lists displayed in the glossary, +unwanted locations will be added to it corresponding to the table of +contents (if present) and every page that contains the entry in the +page header (if the page style in use adds the chapter or section +title to the header); +\item if the page style in use adds the chapter or section title to +the header and attempts to convert it to upper case, the entry label +(in the argument of \cs{gls} etc) will be converted to upper case +and the entry won't be recognised; +\item if you use \sty{hyperref}, commands like \cs{gls} can't be +expanded to a simple string and only the label will appear in the +PDF bookmark (with a warning from \sty{hyperref}); +\item if you use \sty{hyperref}, you will end up with nested hyperlinks +in the table of contents. +\end{itemize} +Similar problems can also occur with captions (except for the page +header and bookmark issues). + +To get around all these problems, the \styfmt{glossaries} user manual +recommends using the expandable non-hyperlink commands, such as +\ics{glsentrytext} (for regular entries) or \ics{glsentryshort} +(for abbreviations). This is the simplest solution, but doesn't +allow for special formatting that's applied to the entry through +commands like \cs{glstext} or \cs{glsxtrshort}. This means that if, +for example, you are using one of the abbreviation styles that uses +\ics{textsc} then the short form displayed with \cs{glsentryshort} won't use small +caps. If you only have one abbreviation style in use, you can +explicitly enclose \cs{glsentryshort}\marg{label} in the argument of +\cs{glsabbrvfont}, like this: +\begin{verbatim} +\chapter{A Chapter about \glsabbrvfont{\glsentryshort{html}}} +\end{verbatim} +Or, if you are using \sty{hyperref}: +\begin{verbatim} +\chapter{A Chapter about +\texorpdfstring{\glsabbrvfont{\glsentryshort{html}}}{\glsentryshort{html}}} +\end{verbatim} + +Since this is a bit cumbersome, you might want to define a new +command to do this for you. However, if you have mixed styles this +won't work as commands like \cs{gls} and \cs{glsxtrshort} redefine +\cs{glsabbrvfont} to match the entry's style before displaying it. +In this case, the above example doesn't take into account the +shifting definitions of \cs{glsabbrvfont} and will use whatever +happens to be the last abbreviation style in use. More complicated +solutions interfere with the upper casing used by the standard +page styles that display the chapter or section title in the page +header using \ics{MakeUppercase}. + +The \styfmt{glossaries-extra} package tries to resolve this by +modifying \ics{markright} and \ics{markboth} and \cs{@starttoc}. If you don't like this +change, you can restore their former definitions using +\begin{definition}[\DescribeMacro\glsxtrRevertMarks] +\cs{glsxtrRevertMarks} +\end{definition} +If you only want to restore \cs{@starttoc} you can use: +\begin{definition}[\DescribeMacro\glsxtrRevertTocMarks] +\cs{glsxtrRevertTocMarks} +\end{definition} +If you restore the header or table of contents commands, you'll have to use the \styfmt{glossaries} manual's +recommendations of either simply using \cs{glsentryshort} (as above) +or use the sectioning command's option argument to provide an +alternative for the table of contents and page header. For example: +\begin{verbatim} +\chapter[A Chapter about \glsentryshort{html}]{A Chapter about \gls{html}} +\end{verbatim} +Alternatively, you need to find a way to insert \cs{glsxtrmarkhook} and +\cs{@glsxtrinmark} at the start of the header or table of contents +either scoped or afterwards cancelled with \cs{@glsxtrnotinmark} and +\cs{glsxtrrestoremarkhook}. + +If you don't revert the mark commands back with +\cs{glsxtrRevertMarks}, you can use the commands described below in +the argument of sectioning commands. You can still use them even +if the mark commands have been reverted, but only where they don't +conflict with the page style. + +The commands listed below all use \ics{texorpdfstring} if +\sty{hyperref} has been loaded so that the expandable non-formatted +version is added to the PDF bookmarks. Note that since the commands +that convert the first letter to upper case aren't expandable, the +non-case-changing version is used for the bookmarks. + +These commands essentially behave as though you have used +\cs{glsxtrshort} (or equivalent) with the options +\gloskey[glslink]{noindex} and \gloskey[glslink]{hyper\eq false}. +The text produced won't be converted to upper case in the page +headings by default. If you want the text converted to upper case +you need to set the \catattr{headuc} attribute to \qt{true} +for the appropriate category. + +\begin{important} +If you use one of the \ics{textsc} styles, be aware that the default +fonts don't provide bold small-caps or italic small-caps. This +means that if the chapter or section title style uses bold, this +may override the small-caps setting, in which case the abbreviation +will just appear as lower case bold. If the heading style uses +italic, the abbreviation may appear in upright small-caps, +\emph{even if you have set the \catattr{headuc} attribute} since +the all-capitals form still uses \cs{glsabbrvfont}. +You may want to consider using the \sty{slantsc} package in this +case. +\end{important} + +Display the short form: +\begin{definition}[\DescribeMacro\glsfmtshort] +\cs{glsfmtshort}\marg{label} +\end{definition} + +Display the plural short form: +\begin{definition}[\DescribeMacro\glsfmtshortpl] +\cs{glsfmtshortpl}\marg{label} +\end{definition} + +First letter upper case singular short form: +\begin{definition}[\DescribeMacro\Glsfmtshort] +\cs{Glsfmtshort}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +First letter upper case plural short form: +\begin{definition}[\DescribeMacro\Glsfmtshortpl] +\cs{Glsfmtshortpl}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +Display the long form: +\begin{definition}[\DescribeMacro\glsfmtlong] +\cs{glsfmtlong}\marg{label} +\end{definition} + +Display the plural long form: +\begin{definition}[\DescribeMacro\glsfmtlongpl] +\cs{glsfmtlongpl}\marg{label} +\end{definition} + +First letter upper case singular long form: +\begin{definition}[\DescribeMacro\Glsfmtlong] +\cs{Glsfmtlong}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +First letter upper case plural long form: +\begin{definition}[\DescribeMacro\Glsfmtlongpl] +\cs{Glsfmtlongpl}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +There are similar commands for the full form, but note that these +use the \emph{inline} full form, which may be different from the +full form used by \cs{gls}. + +Display the full form: +\begin{definition}[\DescribeMacro\glsfmtfull] +\cs{glsfmtfull}\marg{label} +\end{definition} + +Display the plural full form: +\begin{definition}[\DescribeMacro\glsfmtfullpl] +\cs{glsfmtfullpl}\marg{label} +\end{definition} + +First letter upper case singular full form: +\begin{definition}[\DescribeMacro\Glsfmtfull] +\cs{Glsfmtfull}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +First letter upper case plural full form: +\begin{definition}[\DescribeMacro\Glsfmtfullpl] +\cs{Glsfmtfullpl}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +There are also equivalent commands for the value of the +\gloskey{text} field: +\begin{definition}[\DescribeMacro\glsfmttext] +\cs{glsfmttext}\marg{label} +\end{definition} + +First letter converted to upper case: +\begin{definition}[\DescribeMacro\Glsfmttext] +\cs{Glsfmttext}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +The plural equivalents: +\begin{definition}[\DescribeMacro\glsfmtplural] +\cs{glsfmtplural}\marg{label} +\end{definition} +and +\begin{definition}[\DescribeMacro\Glsfmtplural] +\cs{Glsfmtplural}\marg{label} +\end{definition} + +Likewise for the value of the +\gloskey{name} field: +\begin{definition}[\DescribeMacro\glsfmtname] +\cs{glsfmtname}\marg{label} +\end{definition} + +First letter converted to upper case: +\begin{definition}[\DescribeMacro\Glsfmtname] +\cs{Glsfmtname}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +Similarly for the value of the +\gloskey{first} field: +\begin{definition}[\DescribeMacro\glsfmtfirst] +\cs{glsfmtfirst}\marg{label} +\end{definition} + +First letter converted to upper case: +\begin{definition}[\DescribeMacro\Glsfmtfirst] +\cs{Glsfmtfirst}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +The plural equivalents: +\begin{definition}[\DescribeMacro\glsfmtfirstpl] +\cs{glsfmtfirstpl}\marg{label} +\end{definition} +and +\begin{definition}[\DescribeMacro\Glsfmtfirstpl] +\cs{Glsfmtfirstpl}\marg{label} +\end{definition} + +\chapter{Categories} +\label{sec:categories} + +Each entry defined by \ics{newglossaryentry} (or commands that +internally use it such as \ics{newabbreviation}) +is assigned a category +through the \gloskey{category} key. You may add any category that +you like, but since the category is a label used in the creation +of some control sequences, avoid problematic characters within the +category label. (So take care if you have \sty{babel} shorthands on +that make some characters active.) + +The use of categories can give you more control over the way entries +are displayed in the text or glossary. Note that an entry's category +is independent of the glossary type. Be careful not to confuse +\gloskey{category} with \gloskey{type}. + +The default category assumed by +\cs{newglossaryentry} is labelled \category{general}. Abbreviations +defined with \cs{newabbreviation} have the category set to +\category{abbreviation} by default. Abbreviations defined with +\cs{newacronym} have the category set to \category{acronym} by +default. + +Additionally, if you have enabled \ics{newterm} with the +\pkgopt{index} package option that command +will set the category to \category{index} by default. If you have +enabled \ics{glsxtrnewsymbol} with the \pkgopt{symbols} package +option, that command will set the category to \category{symbol}. If you have +enabled \ics{glsxtrnewnumber} with the \pkgopt{numbers} package +option, that command will set the category to \category{number}. + +You can obtain the category label for a given entry using +\begin{definition}[\DescribeMacro\glscategory] +\cs{glscategory}\marg{label} +\end{definition} +This is equivalent to commands like \cs{glsentryname} and so may be +used in an expandable context. No error is generated if the entry +doesn't exist. + +You can test the category for a given entry using +\begin{definition}[\DescribeMacro\glsifcategory] +\cs{glsifcategory}\marg{entry-label}\marg{category-label}\marg{true +part}\marg{false part} +\end{definition} +This is equivalent to +\begin{alltt} +\ics{ifglsfieldeq}\marg{entry-label}\{category\}\marg{category-label}\marg{true +part}\marg{false part} +\end{alltt} +so any restrictions that apply to \cs{ifglsfieldeq} also apply to +\cs{glsifcategory}. + +Each category may have a set of attributes. For example, the +\category{general} and \category{acronym} categories have the +attribute \catattr{regular} set to \qt{true} to indicate that all +entries with either of those categories are regular entries (as +opposed to abbreviations). This attribute is accessed by +\cs{glsentryfmt} to determine whether to use \cs{glsgenentryfmt} or +\cs{glsxtrgenabbrvfmt}. + +Other attributes recognised by \styfmt{glossaries-extra} are: + +\begin{description} + +\item[\catattrdef{nohyperfirst}] When using commands like \ics{gls} +this will automatically suppress the hyperlink on \gls{firstuse} for entries with a +category that has this attribute set to \qt{true}. +(This settings can be overridden by explicitly setting +the \gloskey[glslink]{hyper} key on or off in the optional argument of +commands like \cs{gls}.) As from version 1.07, \cs{glsfirst}, +\cs{Glsfirst}, \cs{GLSfirst} and their plural versions (which should ideally +behave in a similar way to the \gls{firstuse} of \cs{gls} or +\cs{glspl}) now honour +this attribute (but not the package-wide \pkgopt[false]{hyperfirst} +option, which matches the behaviour of \sty{glossaries}). If you +want commands like \cs{glsfirst} to ignore the +\catattr{nohyperfirst} attribute then just redefine +\begin{definition}[\DescribeMacro\glsxtrchecknohyperfirst] +\cs{glsxtrchecknohyperfirst}\marg{label} +\end{definition} +to do nothing. + +\item[\catattrdef{nohyper}] When using commands like \ics{gls} +this will automatically suppress the hyperlink for entries with a +category that has this attribute set to \qt{true}. +(This settings can be overridden by explicitly setting +the \gloskey[glslink]{hyper} key on or off in the optional argument of +commands like \cs{gls}.) + +\item[\catattrdef{indexonlyfirst}] This is similar to the +\pkgopt{indexonlyfirst} package option but only for entries +that have a category with this attribute set to \qt{true}. + +\item[\catattrdef{wrgloss}] When using commands like \ics{gls}, +if this attribute is set to \qt{after}, it will automatically +implement \gloskey[glslink]{wrgloss}\optfmt{=after}. (New to v1.14.) + +\item[\catattrdef{discardperiod}] If set to \qt{true}, the +post-\gls{linktext} hook will +discard a~full stop (period) that follows \emph{non-plural} commands like \cs{gls} or +\cs{glstext}. (Provided for entries such as abbreviations that end +with a full stop.) This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) This attribute +doesn't apply to the accessibility fields. + +Note that this can cause a problem if you access a field that +doesn't end with a full stop. For example: +\begin{verbatim} +\newabbreviation + [user1={German Speaking \TeX\ User Group}] + {dante}{DANTE e.V.}{Deutschsprachige Anwendervereinigung \TeX\ +e.V.} +\end{verbatim} +Here the \gloskey{short} and \gloskey{long} fields end with a full stop, but the +\gloskey{user1} field doesn't. The simplest solution in this +situation is to put the sentence terminator in the final optional +argument. For example: +\begin{verbatim} +\glsuseri{dante}[.] +\end{verbatim} +This will bring the punctuation character inside the \gls{linktext} +and it won't be discarded. + +\item[\catattrdef{pluraldiscardperiod}] If this attribute is set to +\qt{true} \emph{and} the \catattr{discardperiod} attribute is set to +\qt{true}, this will behave as above for the plural commands like +\cs{glspl} or \cs{glsplural}. This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\item[\catattrdef{retainfirstuseperiod}] If this attribute is set +to \qt{true} then the full stop won't be discarded for +\gls{firstuse} instances, even if \catattr{discardperiod} or +\catattr{pluraldiscardperiod} are set. This is useful for +\meta{short} (\meta{long}) abbreviation styles where only the short +form has a trailing full stop. This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) This attribute doesn't apply to the +accessibility fields. + +\item[\catattrdef{markwords}] If this attribute is set to \qt{true} +any entry defined using \ics{newabbreviation} will automatically +have spaces in the long form replaced with +\begin{definition}[\DescribeMacro\glsxtrwordsep] +\cs{glsxtrwordsep} +\end{definition} +and each word is encapsulated with +\begin{definition}[\DescribeMacro\glsxtrword] +\cs{glsxtrword}\marg{word} +\end{definition} +For example: +\begin{verbatim} +\glssetcategoryattribute{abbreviation}{markwords}{true} +\newabbreviation{ip}{IP}{Internet Protocol} +\end{verbatim} +is essentially the same as +\begin{verbatim} +\newabbreviation{ip}{IP} +{\glsxtrword{Internet}\glsxtrwordsep\glsxtrword{Protocol}} +\end{verbatim} +The \qt{hyphen} styles, such as +\abbrstyle{long-hyphen-short-hyphen}, take advantage of this +markup. If the inserted material (provided in the final argument +of commands like \ics{gls}) starts with a hyphen then +\cs{glsxtrwordsep} is locally redefined to a hyphen. (The default +value is a space). Note that this only applies to commands +like \cs{gls} and not like \cs{glsxtrlong}. You can provide your own +localised switch, if required. For example: +\begin{verbatim} +\newcommand{\hyplong}[2][]{% + {\def\glsxtrwordsep{-}\glsxtrlong[#1]{#2}}} +\end{verbatim} + +This setting will also adjust the long plural. This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\begin{important} +This setting may result in the +\cs{glsxtrword} and \cs{glsxtrwordsep} markup ending up in the +\gloskey{sort} field, depending on the style in use. +\end{important} + +\item[\catattrdef{markshortwords}] This is similar to +\catattr{markwords} but applies to the short form. (Only useful for +abbreviations that contain spaces.) This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +This setting will only adjust the short plural if the +\gloskey{shortplural} key isn't used. This setting will +take precedence over \catattr{insertdots}. + +\begin{important} +This setting may result in the +\cs{glsxtrword} and \cs{glsxtrwordsep} markup ending up in the +\gloskey{sort} field, depending on the style in use. +\end{important} + +\item[\catattrdef{insertdots}] If this attribute is set to \qt{true} +any entry defined using \ics{newabbreviation} will automatically +have full stops (periods) inserted after each letter. The entry will +be defined with those dots present as though they had been present +in the \meta{short} argument of \cs{newabbreviation} (rather than +inserting them every time the entry is used). The short plural +form defaults to the new dotted version of the original \meta{short} +form with the plural suffix appended. \emph{This setting is incompatible +with \catattr{markshortwords}.} This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\begin{important} +If you explicitly override +the short plural using the \gloskey{shortplural} key, you must +explicitly insert the dots yourself (since there's no way for the +code to determine if the plural has a suffix that shouldn't be +followed by a dot). +\end{important} + +This attribute is best used with the \catattr{discardperiod} +attribute set to \qt{true}. + +\item[\catattrdef{aposplural}] If this attribute is set to \qt{true}, +\ics{newabbreviation} will insert an apostrophe (') before +the plural suffix for the \emph{short} plural form (unless explicitly +overridden with the \gloskey{shortplural} key). The long plural form +is unaffected by this setting. This setting overrides +\catattr{noshortplural}. This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) Check with your supervisor, publisher or +editor if you want to use this attribute as this +usage is controversial. + + +\item[\catattrdef{noshortplural}] If this attribute is set to +\qt{true}, \ics{newabbreviation} won't append the plural suffix for +the short plural form. This means the \gloskey{short} and +\gloskey{shortplural} values will be the same unless explicitly +overridden. \emph{This setting is incompatible with \catattr{aposplural}.} This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\item[\catattrdef{accessinsertdots}] If this attribute is set to +\qt{true} and the \sty{glossaries-accsupp} package has been loaded +(with the \pkgopt{accsupp} option), then this behaves like +\catattr{insertdots} but for the \gloskey{shortaccess} field instead +of the \gloskey{short} field. This can be used to assist the +screen reader for initialisms that should be read out letter by +letter rather than as a word. For example: +\begin{verbatim} +\glssetcategoryattribute{initialism}{accessinsertdots}{true} + +\newabbreviation[category=initialism]{pi}{PI}{Private Investigator} +\end{verbatim} +This setting will be overridden by an explicit use of +the \gloskey{shortaccess} key in the optional argument +of \cs{newabbreviation} (or \cs{newacronym}). This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\item[\catattrdef{nameshortaccess}] If this attribute is set to +\qt{true}, the \gloskey{access} field (used for the \gloskey{name} +field's accessibility support) is set to the \gloskey{shortaccess} +value. This attribute has no effect if there's no accessibility +support or if the \gloskey{shortaccess} field hasn't been assigned +or if the \gloskey{access} field is used explicitly. This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\item[\catattrdef{textshortaccess}] Like \gloskey{nameshortaccess} +but applies to the \gloskey{textaccess} field (for use with +regular abbreviations). + +\item[\catattrdef{firstshortaccess}] Like \gloskey{nameshortaccess} +but applies to the \gloskey{firstaccess} field (for use with +regular abbreviations). + +\item[\catattrdef{accessaposplural}] This boolean attribute overrides +\catattr{aposplural} for the \gloskey{shortpluralaccess} key. +Has no effect if there's no accessibility support or if +the \gloskey{shortaccess} key hasn't been set or if the +\gloskey{shortpluralaccess} key is explicitly set. If +the \catattr{aposplural} is set and this attribute isn't set +and the \gloskey{shortaccess} key is set, then the +\catattr{aposplural} setting governs the default +\gloskey{shortpluralaccess} setting. If you want +\catattr{aposplural} but don't want it applied to the accessibility +support, set the \catattr{accessaposplural} attribute to \qt{false}. This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\item[\catattrdef{accessnoshortplural}] This boolean attribute overrides +\catattr{noshortplural} for the \gloskey{shortpluralaccess} key. +The same conditions apply as for \catattr{accessaposplural}. This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\item[\catattrdef{headuc}] If this attribute is set to \qt{true}, +commands like \ics{glsfmtshort} will use the upper case version +in the page headers. + +\item[\catattrdef{tagging}] If this attribute is set to \qt{true}, +the tagging command defined by \ics{GlsXtrEnableInitialTagging} +will be activated to use \ics{glsxtrtagfont} in the glossary +(see \sectionref{sec:tagging}). + +\item[\catattrdef{entrycount}] Unlike the above attributes, +this attribute isn't boolean but instead must be an integer +value and is used in combination with \ics{glsenableentrycount} +(see \sectionref{sec:entrycountmods}). Leave blank or undefined +for categories that shouldn't have this facility enabled. The +value of this attribute is used by \ics{glsxtrifcounttrigger} +to determine how commands such as \ics{cgls} should behave. + +With \styfmt{glossaries}, commands like \cs{cgls} use \cs{cglsformat} +only if the previous usage count for that entry was equal to~1. +With \styfmt{glossaries-extra} the test is now for entries that +have the \catattr{entrycount} attribute set and +where the previous usage count for that entry is less than or +equal to the value of that attribute. + +\item[\catattrdef{linkcount}] This attribute is set to +\texttt{true} by \ics{GlsXtrEnableLinkCounting} (see +\sectionref{sec:linkcount}). + +\item[\catattrdef{linkcountmaster}] This attribute is set to +the name of the master counter by \ics{GlsXtrEnableLinkCounting} +if the optional argument is provided (see +\sectionref{sec:linkcount}). + +\item[\catattrdef{glossdesc}] The \ics{glossentrydesc} command +(used in the predefined glossary styles) is modified by +\styfmt{glossaries-extra} to check for this attribute. +The attribute may have one of the following values: +\begin{itemize} +\item \texttt{firstuc}: the first letter of the description will be +converted to upper case (using \ics{Glsentrydesc}). + +\item \texttt{title}: the description will be used in the argument of the +title casing command \ics{capitalisewords} (provided by +\sty{mfirstuc}). If you want to use a different command +you can redefine: +\begin{definition}[\DescribeMacro\glsxtrfieldtitlecasecs] +\cs{glsxtrfieldtitlecasecs}\marg{phrase cs} +\end{definition} +For example: +\begin{verbatim} +\newcommand*{\glsxtrfieldtitlecasecs}[1]{\xcapitalisefmtwords*{#1}} +\end{verbatim} +(Note that the argument to \cs{glsxtrfieldtitlecasecs} +will be a control sequence whose replacement text is the +entry's description, which is why \cs{xcapitalisefmtwords} +is needed instead of \cs{capitalisefmtwords}.) + +\end{itemize} +Any other values of this attribute are ignored. Remember +that there are design limitations for both the first letter +uppercasing and the title casing commands. See the \sty{mfirstuc} +user manual for further details. + +\item[\catattrdef{glossdescfont}] (New to version 1.04) +In addition to the above, the modified \ics{glossentrydesc} +command also checks this attribute. If set, it should be the name of +a control sequence (without the leading backslash) that takes one +argument. This control sequence will be applied to the description +text. For example: +\begin{verbatim} +\glssetcategoryattribute{general}{glossdescfont}{emph} +\end{verbatim} + + +\item[\catattrdef{glossname}] As \catattr{glossdesc} but applies +to \ics{glossentryname}. Additionally, if this attribute is +set to \qt{uc} the name is converted to all capitals. + +\item[\catattrdef{indexname}] If set, the \cs{glsxtrpostnamehook} hook +used at the end of \ics{glossentryname} +will index the entry using \ics{index}. See +\sectionref{sec:autoindex} for further details. + +\item[\catattrdef{glossnamefont}] (New to version 1.04) +In addition to the above, the modified \ics{glossentryname} +command also checks this attribute. If set, it should be the name of +a control sequence (without the leading backslash) that takes one +argument. This control sequence will be applied to the name +text. For example: +\begin{verbatim} +\glssetcategoryattribute{general}{glossnamefont}{emph} +\end{verbatim} +Note that this overrides \cs{glsnamefont} which will only +be used if this attribute hasn't been set. + +Remember that glossary styles may additionally apply a font change, +such as the list styles which put the name in the optional argument +of \cs{item}. + +\item[\catattrdef{textformat}] (New to version 1.21.) +Commands like \cs{gls} and \cs{glstext} have the link text +encapsulated in the argument of \cs{glstextformat} by default. If +this attribute is set, the control sequence given by the attribute +value will be used instead. As with the above, the attribute value +should be the name (without the leading backslash) of a command that +takes a single argument (the link text). Remember that the +abbreviation styles may apply an additional font change. + +\item[\catattrdef{hyperoutside}] (New to v1.21.) The attribute value +may be \texttt{false}, \texttt{true} or unset. If unset, +\texttt{true} is assumed. This indicates the default setting +of the \gloskey[glslink]{hyperoutside} key, described in +\sectionref{sec:wrglossary}. + +\item[\catattrdef{dualindex}] If set, whenever a glossary entry +has information written to the external glossary file +through commands like \ics{gls} and \ics{glsadd}, a~corresponding +line will be written to the indexing file using \ics{index}. See +\sectionref{sec:autoindex} for further details. + +\item[\catattrdef{targeturl}] If set, the hyperlink generated by +commands like \cs{gls} will be set to the URL provided by this +attributes value. For example: +\begin{verbatim} +\glssetcategoryattribute{general}{targeturl}{master-doc.pdf} +\end{verbatim} +(See also the accompanying sample file +\texttt{sample-external.tex}.) If the URL contains awkward +characters (such as \verb|%| or \verb|~|) remember that the base +\styfmt{glossaries} package provides commands like +\ics{glspercentchar} and \cs{glstildechar} that expand to literal +characters. + +If you want to a named anchor within the target URL (notionally +adding \texttt{\#}\meta{name} to the URL), then you also +need to set \catattr{targetname} to the anchor \meta{name}. You may +use \cs{glslabel} within \meta{name} which is set by commands +like \cs{gls} to the entry's label. + +All the predefined glossary styles start each entry +listing with \cs{glstarget} which sets the anchor to +\verb|\glolinkprefix\glslabel|, so if you want entries to link +to glossaries in the URL given by \catattr{targeturl}, you +can just do: +\begin{verbatim} +\glssetcategoryattribute{general}{targetname}{\glolinkprefix\glslabel} +\end{verbatim} +(If the target document changed \cs{glolinkprefix} then you will +need to adjust the above as appropriate.) + +If the anchor is in the form \meta{name1}\texttt{.}\meta{name2} +then use \catattr{targetname} for the \meta{name2} part and +\catattr{targetcategory} for the \meta{name1} part. + +For example: +\begin{verbatim} +\glssetcategoryattribute{general}{targeturl}{master-doc.pdf} +\glssetcategoryattribute{general}{targetcategory}{page} +\glssetcategoryattribute{general}{targetname}{7} +\end{verbatim} +will cause all link text for \texttt{general} entries to +link to \texttt{master-doc.pdf\#page.7} (page 7 of that PDF). + +If you want a mixture in your document of entries that link to +an internal glossary and entries that link to an external URL +then you can use the starred form of \ics{newignoredglossary} +for the external list. For example: +\begin{verbatim} +\newignoredglossary*{external} + +\glssetcategoryattribute{external}{targeturl}{master-doc.pdf} +\glssetcategoryattribute{general}{targetname}{\glolinkprefix\glslabel} + +\newglossaryentry{sample}{name={sample},description={local example}} + +\newglossaryentry{sample2}{name={sample2}, + type=external, + category=external, + description={external example}} +\end{verbatim} + +\item[\catattrdef{externallocation}] The value should be the +file name of the target document when manually indexing an +external location (see \sectionref{sec:wrglossary}). In general, +it's better to use \gls{bib2gls} v1.7+ which can handle multiple +external sources and doesn't require this attribute. + +\end{description} + +An attribute can be set using: +\begin{definition}[\DescribeMacro\glssetcategoryattribute] +\cs{glssetcategoryattribute}\marg{category-label}\marg{attribute-label}\marg{value} +\end{definition} +where \meta{category-label} is the category label, +\meta{attribute-label} is the attribute label and \meta{value} is +the new value for the attribute. + +There is a shortcut version to set the \catattr{regular} attribute +to \qt{true}: +\begin{definition}[\DescribeMacro\glssetregularcategory] +\cs{glssetregularcategory}\marg{category-label} +\end{definition} + +If you need to lookup the category label for a particular entry, you +can use the shortcut command: +\begin{definition}[\DescribeMacro\glssetattribute] +\cs{glssetattribute}\marg{entry-label}\marg{attribute-label}\marg{value} +\end{definition} +This uses \cs{glssetcategoryattribute} with \cs{glscategory} to set +the attribute. Note that this will affect all other entries that +share this entry's category. + +You can fetch the value of an attribute for a particular category +using: +\begin{definition}[\DescribeMacro\glsgetcategoryattribute] +\cs{glsgetcategoryattribute}\marg{category-label}\marg{attribute-label} +\end{definition} +Again there is a shortcut if you need to lookup the category label +for a given entry: +\begin{definition}[\DescribeMacro\glsgetattribute] +\cs{glsgetattribute}\marg{entry-label}\marg{attribute-label} +\end{definition} + +You can test if an attribute has been assigned to a given +category using: +\begin{definition}[\DescribeMacro\glshascategoryattribute] +\cs{glshascategoryattribute}\marg{category-label}\marg{attribute-label}\marg{true +code}\marg{false code} +\end{definition} +This uses \sty{etoolbox}'s +\cs{ifcsvoid} and does \meta{true code} if the attribute has been +set and isn't blank and isn't \cs{relax}. The shortcut if you need +to lookup the category label from an entry is: +\begin{definition}[\DescribeMacro\glshasattribute] +\cs{glshasattribute}\marg{entry-label}\marg{attribute-label}\marg{true +code}\marg{false code} +\end{definition} + +You can test the value of an attribute for a particular category +using: +\begin{definition}[\DescribeMacro\glsifcategoryattribute] +\cs{glsifcategoryattribute}\marg{category-label}\marg{attribute-label}\marg{value} \marg{true-part}\marg{false-part} +\end{definition} +This tests if the attribute (given by \meta{attribute-label}) for +the category (given by \meta{category-label}) is set and equal to +\meta{value}. If true, \meta{true-part} is done. If the attribute +isn't set or is set but isn't equal to \meta{value}, \meta{false +part} is done. + +For example: +\begin{verbatim} +\glsifcategoryattribute{general}{nohyper}{true}{NO HYPER}{HYPER} +\end{verbatim} +This does \qt{NO HYPER} if the \category{general} category has the +\catattr{nohyper} attribute set to \texttt{true} otherwise if +does \qt{HYPER}. + +With boolean-style attributes like \catattr{nohyper}, make sure you +always test for \texttt{true} not \texttt{false} in case the attribute hasn't been set. + +Again there's a shortcut if you need to lookup the category label +from a particular entry: +\begin{definition}[\DescribeMacro\glsifattribute] +\cs{glsifattribute}\marg{entry-label}\marg{attribute-label}\marg{value}\marg{true-part} \marg{false-part} +\end{definition} + +There's also a shortcut to determine if a particular category has +the \catattr{regular} attribute set to \qt{true}: +\begin{definition}[\DescribeMacro\glsifregularcategory] +\cs{glsifregularcategory}\marg{category-label}\marg{true-part}\marg{false-part} +\end{definition} +Alternatively, if you need to lookup the category for a particular +entry: +\begin{definition}[\DescribeMacro\glsifregular] +\cs{glsifregular}\marg{entry-label}\marg{true-part}\marg{false-part} +\end{definition} +Note that if the \catattr{regular} attribute hasn't be set, the +above do \meta{false-part}. There are also reverse commands that +test if the \catattr{regular} attribute has been set to \qt{false}: +\begin{definition}[\DescribeMacro\glsifnotregularcategory] +\cs{glsifnotregularcategory}\marg{category-label}\marg{true-part}\marg{false-part} +\end{definition} +or for a particular entry: +\begin{definition}[\DescribeMacro\glsifnotregular] +\cs{glsifnotregular}\marg{entry-label}\marg{true-part}\marg{false-part} +\end{definition} +Again, if the \catattr{regular} attribute hasn't been set, the above +do \meta{false-part}, so these reverse commands aren't logically +opposite in the strict sense. + +You can iterate through all entries with a given category using: +\begin{definition} +\cs{glsforeachincategory}\oarg{glossary-labels}\marg{category-label} \marg{glossary-cs}\marg{label-cs}\marg{body} +\end{definition} +This iterates through all entries in the glossaries identified by +the comma-separated list \meta{glossary-labels} that have the +category given by \meta{category-label} and performs \meta{body} for +each match. Within \meta{body}, you can use \meta{glossary-cs} and +\meta{label-cs} +(which much be control sequences) to access the current glossary and +entry label. If \meta{glossary-labels} is omitted, all glossaries +are assumed. + +Similarly, you can iterate through all entries that have a category +with a given attribute using: +\begin{definition}[\DescribeMacro\glsforeachwithattribute] +\cs{glsforeachwithattribute}\oarg{glossary-labels}\marg{attribute-label} \marg{attribute-value}\marg{glossary-cs}\marg{label-cs}\marg{body} +\end{definition} +This will do \meta{body} for each entry that has a category with the +attribute \meta{attribute-label} set to \meta{attribute-value}. +The remaining arguments are as the previous command. + +You can change the category for a particular entry using the +standard glossary field changing commands, such as +\ics{glsfielddef}. Alternatively, you can use +\begin{definition}[\DescribeMacro\glsxtrsetcategory] +\cs{glsxtrsetcategory}\marg{entry-labels}\marg{category-label} +\end{definition} +This will change the category to \meta{category-label} for each +entry listed in the comma-separated list \meta{entry-labels}. This +command uses \ics{glsfieldxdef} so it will expand +\meta{category-label} and make the change global. + +You can also change the category for all entries with a glossary or +glossaries using: +\begin{definition}[\DescribeMacro\glsxtrsetcategoryforall] +\cs{glsxtrsetcategoryforall}\marg{glossary-labels}\marg{category-label} +\end{definition} +where \meta{glossary-labels} is a comma-separated list of glossary +labels. + +\chapter{Counting References} +\label{sec:countref} + +There are three basic ways of counting entry references: +\begin{enumerate} +\item Counting the total number of times \cs{glsunset} is used +(\cs{glsreset} resets the count and is best avoided). +This is provided by the base \styfmt{glossaries} package and is +intended for documents where the term should be displayed +differently if it's only been used a certain number of times. +The information has to be written to the \texttt{.aux} file +so that it's available on the next \LaTeX\ run. + +This method is extended by \styfmt{glossaries-extra} and is +described in \sectionref{sec:entrycount}. + +\item Counting the total number of records. This method is +only available with \gls{bib2gls} and is intended +for documents where the term should be displayed differently +if it's only been recorded (indexed) a certain number of times. +See \sectionref{sec:recordcount} for further details. + +\item Counting the number of times the \cs{gls}-like or +\cs{glstext}-like commands are used. (That is, those commands +that internally use \cs{@gls@link}.) Unlike the other two methods, +this just provides a running total rather than the total from the +previous \LaTeX\ run. This method is intended to make it more +convenient to work with hooks like \cs{glslinkcheckfirsthyperhook}, +\cs{glslinkpostsetkeys} or \cs{glslinkpresetkeys}. +See \sectionref{sec:linkcount} for further details. +\end{enumerate} + +\section{Entry Counting (First Use Flag)} +\label{sec:entrycount} + +As mentioned in \sectionref{sec:entrycountmods}, +\styfmt{glossaries-extra} modifies the \ics{glsenableentrycount} command to allow +for the \catattr{entrycount} attribute. This means that +you not only need to enable entry counting with +\ics{glsenableentrycount}, but you also need +to set the appropriate attribute (see \sectionref{sec:categories}). + +\begin{important} +Remember that entry counting only counts the number of times an +entry is used by commands that change the \gls{firstuseflag}. (That +is, all those commands that mark the entry as having been used.) +There are many commands that don't modify this flag and they won't +contribute to the entry use count. +\end{important} + +With \styfmt{glossaries-extra}, you may use \ics{cgls} instead of +\ics{gls} even if you haven't enabled entry counting. You will only +get a warning if you use \cs{glsenableentrycount} without setting +the \catattr{entrycount} attribute. (With \styfmt{glossaries}, +commands like \ics{cgls} will generate a warning if +\cs{glsenableentrycount} hasn't been used.) The abbreviation +shortcut \ics{ab} uses \cs{cgls} (see +\sectionref{sec:abbrshortcuts}). The acronym shortcut +\ics{ac} uses \cs{cgls} if it's been defined with +\pkgopt[ac]{shortcuts} (or \pkgopt[all]{shortcuts}) +but uses \cs{gls} if it's been defined with +\pkgopt[acronyms]{shortcuts} (or \pkgopt[acro]{shortcuts}). + +All upper case versions (not provided by \styfmt{glossaries}) are +also available: +\begin{definition}[\DescribeMacro\cGLS] +\cs{cGLS}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +and +\begin{definition}[\DescribeMacro\cGLSpl] +\cs{cGLSpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +These are analogous to \cs{cgls} and \cs{cglspl} but they +use +\begin{definition}[\DescribeMacro\cGLSformat] +\cs{cGLSformat}\marg{label}\marg{insert} +\end{definition} +and +\begin{definition}[\DescribeMacro\cGLSplformat] +\cs{cGLSplformat}\marg{label}\marg{insert} +\end{definition} +which convert the analogous \cs{cglsformat} and +\cs{cglsplformat} to upper case. + +Just using \styfmt{glossaries}: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\makeglossaries + +\glsenableentrycount + +\newacronym{html}{HTML}{hypertext markup language} +\newacronym{xml}{XML}{extensible markup language} + +\begin{document} + +Used once: \cgls{html}. + +Used twice: \cgls{xml} and \cgls{xml}. + +\printglossaries + +\end{document} +\end{verbatim} + +If you switch to \styfmt{glossaries-extra} you must set the +\catattr{entrycount} attribute: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries-extra} + +\makeglossaries + +\glsenableentrycount + +\glssetcategoryattribute{abbreviation}{entrycount}{1} + +\newabbreviation{html}{HTML}{hypertext markup language} +\newabbreviation{xml}{XML}{extensible markup language} + +\begin{document} + +Used once: \cgls{html}. + +Used twice: \cgls{xml} and \cgls{xml}. + +\printglossaries + +\end{document} +\end{verbatim} + +When activated with \cs{glsenableentrycount}, commands such as +\ics{cgls} now use +\begin{definition}[\DescribeMacro\glsxtrifcounttrigger] +\cs{glsxtrifcounttrigger}\marg{label}\marg{trigger code}\marg{normal +code} +\end{definition} +to determine if the entry trips the entry count trigger. +The \meta{trigger code} uses commands like \cs{cglsformat} and +unsets the \gls{firstuseflag}. The \meta{normal code} is the code that +would ordinarily be performed by whatever the equivalent +command is (for example, \cs{cgls} will use \cs{cglsformat} in +\meta{trigger code} but the usual \cs{gls} behaviour in \meta{normal +code}). + +The default definition is: +\begin{verbatim} +\newcommand*{\glsxtrifcounttrigger}[3]{% + \glshasattribute{#1}{entrycount}% + {% + \ifnum\glsentryprevcount{#1}>\glsgetattribute{#1}{entrycount}\relax + #3% + \else + #2% + \fi + }% + {#3}% +} +\end{verbatim} +This means that if an entry is assigned to a category that has +the \catattr{entrycount} attribute then the \meta{trigger code} +will be used if the previous count value +(the number of times the entry was used on the last run) is greater +than the value of the attribute. + +For example, to trigger normal use if the previous count value +is greater than four: +\begin{verbatim} +\glssetcategoryattribute{abbreviation}{entrycount}{4} +\end{verbatim} + +There is a convenient command provided to enable entry counting, +set the \catattr{entrycount} attribute and redefine \ics{gls}, +etc to use \ics{cgls} etc: +\begin{definition}[\DescribeMacro\GlsXtrEnableEntryCounting] +\cs{GlsXtrEnableEntryCounting}\marg{categories}\marg{value} +\end{definition} +The first argument \meta{categories} is a comma-separated list +of categories. For each category, the \catattr{entrycount} +attribute is set to \meta{value}. In addition, this does: +\begin{verbatim} +\renewcommand*{\gls}{\cgls}% +\renewcommand*{\Gls}{\cGls}% +\renewcommand*{\glspl}{\cglspl}% +\renewcommand*{\Glspl}{\cGlspl}% +\renewcommand*{\GLS}{\cGLS}% +\renewcommand*{\GLSpl}{\cGLSpl}% +\end{verbatim} +This makes it easier to enable entry-counting on existing +documents. + +If you use \cs{GlsXtrEnableEntryCounting} more than once, subsequent uses will +just set the \catattr{entrycount} attribute for each listed +category. + +The above example document can then become: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries-extra} + +\makeglossaries + +\GlsXtrEnableEntryCounting{abbreviation}{1} + +\newabbreviation{html}{HTML}{hypertext markup language} +\newabbreviation{xml}{XML}{extensible markup language} + +\begin{document} + +Used once: \gls{html}. + +Used twice: \gls{xml} and \gls{xml}. + +\printglossaries + +\end{document} +\end{verbatim} + +The standard entry-counting function describe above counts +the number of times an entry has been marked as used throughout +the document. (The reset commands will reset the total back to +zero.) If you prefer to count per sectional-unit, you can +use +\begin{definition}[\DescribeMacro\GlsXtrEnableEntryUnitCounting] +\cs{GlsXtrEnableEntryUnitCounting}\marg{categories}\marg{value}\marg{counter-name} +\end{definition} +where \meta{categories} is a comma-separated list of categories +to which this feature should be applied, \meta{value} is the +trigger value and \meta{counter-name} is the name of the counter +used by the sectional unit. + +\begin{important} +Due to the asynchronous nature of \TeX's output routine, +discrepancies will occur in page spanning paragraphs if you +use the \ctr{page} counter. +\end{important} + +Note that you can't use both the document-wide counting and +the per-unit counting in the same document. + +The counter value is used as part of a label, which means +that \cs{the}\meta{counter-name} needs to be expandable. +Since \sty{hyperref} also has a similar requirement and provides +\cs{theH}\meta{counter-name} as an expandable alternative, +\styfmt{glossaries-extra} will use \cs{theH}\meta{counter-name} +if it exists otherwise it will use \cs{the}\meta{counter-name}. + +The per-unit counting function uses two attributes: \catattr{entrycount} +(as before) and \catattr{unitcount} (the name of the counter). + +Both the original document-wide counting mechanism and the +per-unit counting mechanism provide a command that can be +used to access the current count value for this run: +\begin{definition}[\DescribeMacro\glsentrycurrcount] +\cs{glsentrycurrcount}\marg{label} +\end{definition} +and the final value from the previous run: +\begin{definition}[\DescribeMacro\glsentryprevcount] +\cs{glsentryprevcount}\marg{label} +\end{definition} +In the case of the per-unit counting, this is the final value +\emph{for the current unit}. In both commands \meta{label} +is the entry's label. + +The per-unit counting mechanism additionally provides: +\begin{definition}[\DescribeMacro\glsentryprevtotalcount] +\cs{glsentryprevtotalcount}\marg{label} +\end{definition} +which gives the sum of all the per-unit totals from the previous run +for the entry given by \meta{label}, and +\begin{definition}[\DescribeMacro\glsentryprevmaxcount] +\cs{glsentryprevmaxcount}\marg{label} +\end{definition} +which gives the maximum per-unit total from the previous run. + +The above two commands are unavailable for the document-wide counting. + +Example of per-unit counting, where the unit is the chapter: +\begin{verbatim} +\documentclass{report} +\usepackage{glossaries-extra} + +\GlsXtrEnableEntryUnitCounting{abbreviation}{2}{chapter} + +\makeglossaries + +\newabbreviation{html}{HTML}{hypertext markup language} +\newabbreviation{css}{CSS}{cascading style sheet} + +\newglossaryentry{sample}{name={sample},description={sample}} + +\begin{document} +\chapter{Sample} + +Used once: \gls{html}. + +Used three times: \gls{css} and \gls{css} and \gls{css}. + +Used once: \gls{sample}. + +\chapter{Another Sample} + +Used once: \gls{css}. + +Used twice: \gls{html} and \gls{html}. + +\printglossaries +\end{document} +\end{verbatim} +In this document, the \texttt{css} entry is used three times in the +first chapter. This is more than the trigger value of 2, so +\verb|\gls{css}| is expanded on \gls{firstuse} with the short +form used on subsequent use, and the \texttt{css} entries in +that chapter are added to the glossary. In the second chapter, +the \texttt{css} entry is only used once, which trips the +suppression trigger, so in that chapter, the long form +is used and \verb|\gls{css}| doesn't get a line added to +the glossary file. + +The \texttt{html} is used a total of three times, but the +expansion and indexing suppression trigger is tripped +in both chapters because the per-unit total (1 for the first +chapter and 2 for the second chapter) is less than or equal +to the trigger value. + +The \texttt{sample} entry has only been used once, but it doesn't +trip the indexing suppression because it's in the \category{general} +category, which hasn't been listed in +\cs{GlsXtrEnableEntryUnitCounting}. + +The per-unit entry counting can be used for other purposes. +In the following example document the trigger value is set +to zero, which means the index suppression won't be triggered, +but the unit entry count is used to automatically suppress the +hyperlink for commands like \ics{gls} by modifying the +hook +\begin{definition}[\DescribeMacro\glslinkcheckfirsthyperhook] +\cs{glslinkcheckfirsthyperhook} +\end{definition} +which is used at the end of the macro the determines whether +or not to suppress the hyperlink. + +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage{glossaries-extra} + +\makeglossaries + +\GlsXtrEnableEntryUnitCounting{general}{0}{page} + +\newglossaryentry{sample}{name={sample},description={an example}} + +\renewcommand*{\glslinkcheckfirsthyperhook}{% + \ifnum\glsentrycurrcount\glslabel>0 + \setkeys{glslink}{hyper=false}% + \fi +} + +\begin{document} + +A \gls{sample} entry. +Next use: \gls{sample}. + +\newpage + +Next page: \gls{sample}. +Again: \gls{sample}. + +\printglossaries + +\end{document} +\end{verbatim} +This only produces a hyperlink for the first instance of +\verb|\gls{sample}| on each page. + +The earlier warning about using the \ctr{page} counter still +applies. If the first instance of \cs{gls} occurs at the top of the +page within a paragraph that started on the previous page, then +the count will continue from the previous page. + +\section{Link Counting} +\label{sec:linkcount} + +As from version 1.26, an alternative method of entry counting +is to count the number of times the \cs{gls}-like or +\cs{glstext}-like commands are used. (The \qt{link} in this method's +name refers to the use of the internal command \cs{@gls@link} +not to \cs{hyperlink} although \cs{@gls@link} may use +\cs{hyperlink} when displaying the \gls{linktext}.) + +To enable link counting use the preamble-only command: +\begin{definition}[\DescribeMacro\GlsXtrEnableLinkCounting] +\cs{GlsXtrEnableLinkCounting}\oarg{master counter}\marg{categories} +\end{definition} +where \meta{categories} is a list of category labels. The optional +argument \meta{master counter} may be used to identify a master +counter (which must be defined). If present, the associated +link counter will be reset when the master counter is incremented. +This command automatically sets the \catattr{linkcount} attribute +for the given categories. If the optional argument is +present, it also sets the \catattr{linkcountmaster} attribute. + +When enabled, commands like \cs{gls} and \cs{glstext} +increment the associated counter using +\begin{definition}[\DescribeMacro\glsxtrinclinkcounter] +\cs{glsxtrinclinkcounter}\marg{counter name} +\end{definition} +This just does +\texttt{\cs{stepcounter}\marg{counter name}} by default but if you +need \cs{refstepcounter} instead, just redefine this command: +\begin{verbatim} +\renewcommand*{\glsxtrinclinkcounter}[1]{\refstepcounter{#1}} +\end{verbatim} + +You can access the internal count register using +\begin{definition}[\DescribeMacro\GlsXtrLinkCounterValue] +\cs{GlsXtrLinkCounterValue}\marg{label} +\end{definition} +where \meta{label} is the entry's label. This will expand +to 0 if the counter hasn't been defined. + +It's also possible to access the display value +(\cs{the}\meta{counter}) using +\begin{definition}[\DescribeMacro\GlsXtrTheLinkCounter] +\cs{GlsXtrTheLinkCounter}\marg{counter} +\end{definition} +(This will expand to 0 if the counter hasn't been defined.) + +\begin{important} +In order to conserve resources, the counter is only defined +when it first needs to be incremented so terms that have +been defined but haven't been used in the document +won't have the associated count register allocated. +\end{important} + +You can test if the counter has been defined using: +\begin{definition}[\DescribeMacro\GlsXtrIfLinkCounterDef] +\cs{GlsXtrIfLinkCounterDef}\marg{label}\marg{true}\marg{false} +\end{definition} +where \meta{label} is the entry's label. + +The counter name can be obtained using +\begin{definition}[\DescribeMacro\GlsXtrLinkCounterName] +\cs{GlsXtrLinkCounterName}\marg{label} +\end{definition} +This simply expands to the counter name associated with the +entry given by \meta{label} without any check for +existence. For example, to change the display command +(\cs{the}\meta{counter}) using \sty{etoolbox}: +\begin{verbatim} +\csdef{the\GlsXtrLinkCounterName{duck}}{\Roman{\GlsXtrLinkCounterName{duck}}} +\end{verbatim} +This is useful if you just want to change the display for +specific entries but isn't convenient if you want to change the +display for all entries. Instead, it's simpler to redefine +\cs{GlsXtrTheLinkCounter}. For example: +\begin{verbatim} +\renewcommand*{\GlsXtrTheLinkCounter}[1]{% + \GlsXtrIfLinkCounterDef{#1}% + {\Roman{\GlsXtrLinkCounterName{#1}}}% + {0}% +} +\end{verbatim} +In both cases, the redefinition should be implemented +after \cs{GlsXtrEnableLinkCounting}. + +Here's an example document that uses link counting to disable +the hyperlink after the first reference. This redefines +\ics{glslinkpresetkeys} (which is used by both \cs{gls} +and \cs{glstext}) instead of +\cs{glslinkcheckfirsthyperhook} (which is used by \cs{gls} +but not by \cs{glstext}). + +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage{glossaries-extra} + +\makeglossaries + +\renewcommand*{\glslinkpresetkeys}{% + \ifnum\GlsXtrLinkCounterValue{\glslabel}>1 + \setkeys{glslink}{hyper=false}% + \fi +} + +\GlsXtrEnableLinkCounting{general} + +\newglossaryentry{sample1}{name={sample1},description={an example}} +\newglossaryentry{sample2}{name={sample2},description={another example}} + +\newabbreviation{ex}{ex}{example} + +\begin{document} + +\section{Sample Section} + +\Gls{sample1}, \gls{sample2} and \gls{ex}. +\Glstext{sample1} and \gls{ex} again. + +\section{Another Sample Section} + +\Gls{sample1}, \gls{sample2} and \gls{ex}. + +\printglossaries + +\end{document} +\end{verbatim} +The use of \ics{glslinkpresetkeys} +means that the options can override this. For example +\begin{verbatim} +\gls[hyper=true]{sample1} +\end{verbatim} +will override the \texttt{hyper=false} setting in +\ics{glslinkpresetkeys}. If \ics{glslinkpostsetkeys} is used +instead, the \texttt{hyper=false} setting will override +the setting provided in the optional argument. + +The \category{abbreviation} category doesn't have the +\catattr{linkcount} attribute set (since it's not +listed in the argument of \cs{GlsXtrEnableLinkCounting}). This means that +\cs{GlsXtrLinkCounterValue} +always expands to 0 for the abbreviation (\texttt{ex}), so the +inequality test +\begin{verbatim} +\ifnum\GlsXtrLinkCounterValue{\glslabel}>1 +\end{verbatim} +will always be false. This means that the abbreviation won't +have \texttt{hyper=false} applied. If the test is changed to +\begin{verbatim} +\ifnum\GlsXtrLinkCounterValue{\glslabel}=1 +\else + \setkeys{glslink}{hyper=false}% +\fi +\end{verbatim} +Then the abbreviation will always have \texttt{hyper=false} +applied. + +To reset the counter every section use the optional argument to set +the master counter: +\begin{verbatim} +\GlsXtrEnableLinkCounting[section]{general} +\end{verbatim} + +\chapter{Auto-Indexing} +\label{sec:autoindex} + +It's possible that you may also want a normal index as well as +the glossary, and you may want entries to automatically be +added to the index (as in this document). +There are two attributes that govern this: \catattr{indexname} +and \catattr{dualindex}. + +\begin{important} +The auto-indexing is designed for \gls{makeindex} syntax. If you've +used the \pkgopt{xindy} package option, the automatic escaping of +\gls{xindy} special characters in the \gloskey{sort} field may +result in an incorrect sort value for the \cs{index} command used by +the auto-indexing. Note also that \app{texindy} has a fixed set of +special characters (corresponding to \gls{makeindex}['s] defaults) +that can't be customized. You may want to consider using \gls{bib2gls} and +its dual entries as an alternative approach. +\end{important} + +\begin{sloppypar} +The \ics{glsxtrpostnamehook} macro, used +at the end of \ics{glossentryname} and \ics{Glossentryname}, +checks the \catattr{indexname} attribute for the category +associated with that entry. +Since \cs{glossentryname} is used in the default glossary +styles, this makes a convenient way of automatically indexing +each entry name at its location in the glossary without +fiddling around with the value of the \gloskey{name} key. +\end{sloppypar} + +The internal macro used by the \styfmt{glossaries} package to +write the information to the external glossary file is +modified to check for the \catattr{dualindex} attribute. + +In both cases, the indexing is done through +\begin{definition}[\DescribeMacro\glsxtrdoautoindexname] +\cs{glsxtrdoautoindexname}\marg{label}\marg{attribute-label} +\end{definition} +This uses the standard \ics{index} command with the sort value +taken from the entry's \gloskey{sort} key and the actual value +set to \cs{glsentryname}\marg{label}. As from v1.16, there are +user-level commands available to change the sort and actual +value used by the automated index. + +The actual value is given by +\begin{definition}[\DescribeMacro\glsxtrautoindexentry] +\cs{glsxtrautoindexentry}\marg{label} +\end{definition} +where \meta{label} is the entry's label. The default definition +is: +\begin{verbatim} +\newcommand*{\glsxtrautoindexentry}[1]{\string\glsentryname{#1}} +\end{verbatim} +Note the use of \cs{string} to prevent \cs{glsentryname} from +being expanded as it's written to the index file. + +The sort value is assigned using: +\begin{definition}[\DescribeMacro\glsxtrautoindexassignsort] +\cs{glsxtrautoindexassignsort}\marg{cs}\marg{label} +\end{definition} +where \meta{label} is the entry label and \meta{cs} is the command +which needs to be set to the sort value. The default definition is: +\begin{verbatim} +\newcommand*{\glsxtrautoindexassignsort}[2]{% + \glsletentryfield{#1}{#2}{sort}% +} +\end{verbatim} +After this macro is called, \meta{cs} is then processed to escape +any of \app{makeindex}'s special characters. Note that this +escaping is only performed on the sort not on the actual value. +The escaping of the sort value is performed by +\begin{definition}[\DescribeMacro\glsxtrautoindexesc] +\cs{glsxtrautoindexesc} +\end{definition} +You can redefine this to do nothing if you want to omit the +escaping. You may want to consider providing another field to obtain +the appropriate sort value if the one provided in the \gloskey{sort} +field isn't suitable (because it may already have had special +characters escaped or it may be a numeric value in the case of +sort by use or definition). + +The command used to perform the actual indexing is: +\begin{definition}[\DescribeMacro\glsxtrautoindex] +\cs{glsxtrautoindex}\marg{text} +\end{definition} +This just does \cs{index}\marg{text} by default. + +\begin{important} +The entry's \gloskey{parent} field isn't referenced in this +automated indexing. +\end{important} + +For example, to index the value of the \gloskey{first} key, +instead of the \gloskey{name} key: +\begin{verbatim} +\renewcommand*{\glsxtrautoindexentry}[1]{\string\glsentryfirst{#1}} +\end{verbatim} +and if the sort value also needs to be set to the \gloskey{long} +field, if present, otherwise the \gloskey{sort} field: +\begin{verbatim} +\renewcommand*{\glsxtrautoindexassignsort}[2]{% + \ifglshaslong{#2}% + {\glsletentryfield{#1}{#2}{long}}% + {\glsletentryfield{#1}{#2}{sort}}% +} +\end{verbatim} + +If the value of the attribute given by \meta{attribute-label} +is \qt{true}, no encap +will be added, otherwise the encap will be the +attribute value. For example: +\begin{verbatim} +\glssetcategoryattribute{general}{indexname}{textbf} +\end{verbatim} +will set the encap to \texttt{textbf} which will display the +relevant page number in bold whereas +\begin{verbatim} +\glssetcategoryattribute{general}{dualindex}{true} +\end{verbatim} +won't apply any formatting to the page number in the index. + +\begin{important} +The location used in the index will always be the page number +not the counter used in the glossary. (Unless some other loaded +package has modified the definition of \cs{index} to use +some thing else.) +\end{important} + +By default the \gloskey[glslink]{format} key won't be used with +the \catattr{dualindex} attribute. You can allow the +\gloskey[glslink]{format} key to override the attribute value +by using the preamble-only command: +\begin{definition}[\DescribeMacro\GlsXtrEnableIndexFormatOverride] +\cs{GlsXtrEnableIndexFormatOverride} +\end{definition} +If you use this command and \sty{hyperref} has been loaded, +then the \env{theindex} environment will be modified to redefine +\ics{glshypernumber} to allow formats that use that command. + +\begin{important} +The \catattr{dualindex} attribute will still be used on +subsequent use even if the \catattr{indexonlyfirst} attribute +(or \pkgopt{indexonlyfirst} package option) is set. However, +the \catattr{dualindex} attribute will honour the +\gloskey[glslink]{noindex} key. +\end{important} + +The \cs{glsxtrdoautoindexname} command will attempt to escape any of +\ics{makeindex}'s special characters, but there may be special cases +where it fails, so take care. This assumes the default \gls{makeindex} actual, +level, quote and encap values (unless any of the commands +\ics{actualchar}, \ics{levelchar}, \ics{quotechar} or +\ics{encapchar} have been defined before \styfmt{glossaries-extra} +is loaded). + +If this isn't the case, you can use the following preamble-only +commands to set the correct characters. +\begin{important} +Be very careful of possible shifting category codes! +\end{important} + +\begin{definition}[\DescribeMacro\GlsXtrSetActualChar] +\cs{GlsXtrSetActualChar}\marg{char} +\end{definition} +Set the actual character to \meta{char}. + +\begin{definition}[\DescribeMacro\GlsXtrSetLevelChar] +\cs{GlsXtrSetLevelChar}\marg{char} +\end{definition} +Set the level character to \meta{char}. + +\begin{definition}[\DescribeMacro\GlsXtrSetEscChar] +\cs{GlsXtrSetEscChar}\marg{char} +\end{definition} +Set the escape (quote) character to \meta{char}. + +\begin{definition}[\DescribeMacro\GlsXtrSetEncapChar] +\cs{GlsXtrSetEncapChar}\marg{char} +\end{definition} +Set the encap character to \meta{char}. + +\chapter{On-the-Fly Document Definitions} +\label{sec:onthefly} + +\begin{important} +The commands described here may superficially look like +\meta{word}\cs{index}\marg{word}, but they behave rather +differently. If you want to use \cs{index} then just use +\cs{index}. +\end{important} + +The \styfmt{glossaries} package advises against defining entries +in the \env{document} environment. As mentioned in +\sectionref{sec:pkgopts} above, this ability is disabled by +default with \styfmt{glossaries-extra} but can be enabled using +the \pkgopt{docdefs} package options. + +Although this can be problematic, the \styfmt{glossaries-extra} +package provides a way of defining and using entries within +the \env{document} environment without the tricks used with the +\pkgopt{docdefs} option. \emph{There are limitations with this +approach, so take care with it.} This function is disabled by +default, but can be enabled using the preamble-only command: +\begin{definition}[\DescribeMacro\GlsXtrEnableOnTheFly] +\cs{GlsXtrEnableOnTheFly} +\end{definition} +When used, this defines the commands described below. + +\begin{important} +The commands \cs{glsxtr}, \cs{glsxtrpl}, \cs{Glsxtr} +and \cs{Glsxtrpl} can't be used after the glossaries have been +displayed (through \ics{printglossary} etc). It's best not to mix +these commands with the standard glossary commands, such +as \cs{gls} or there may be unexpected results. +\end{important} + +\begin{definition}[\DescribeMacro\glsxtr] +\cs{glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label} +\end{definition} +If an entry with the label \meta{label} has already been defined, +this just does \cs{gls}\oarg{gls-options}\marg{label}. If +\meta{label} hasn't been defined, this will define the entry +using: +\begin{alltt} +\cs{newglossaryentry}\marg{label}\{name=\marg{label}, + category=\cs{glsxtrcat}, + description=\{\cs{nopostdesc}\}, + \meta{dfn-options}\} +\end{alltt} + +\begin{important} +The \meta{label} must contain any non-expandable commands, such as +formatting commands or problematic characters. +If the term requires any of these, they must be omitted from the +\meta{label} and placed in the \gloskey{name} key must be provided +in the optional argument \meta{dfn-options}. +\end{important} + +The second optional argument \meta{dfn-options} should be empty +if the entry has already been defined, since it's too late for +them. If it's not empty, a~warning will be generated with +\begin{definition}[\DescribeMacro\GlsXtrWarning] +\cs{GlsXtrWarning}\marg{dfn-options}\marg{label} +\end{definition} + +For example, this warning will be generated on the second instance +of \cs{glsxtr} below: +\begin{verbatim} +\glsxtr[][plural=geese]{goose} +% ... later +\glsxtr[][plural=geese]{goose} +\end{verbatim} + +If you are considering doing something like: +\begin{verbatim} +\newcommand*{\goose}{\glsxtr[][plural=geese]{goose}} +\renewcommand*{\GlsXtrWarning}[2]{} +% ... later +\goose\ some more text here +\end{verbatim} +then don't bother. It's simpler and less problematic to just +define the entries in the preamble with \ics{newglossaryentry} +and then use \cs{gls} in the document. + +There are plural and case-changing alternatives to \cs{glsxtr}: +\begin{definition}[\DescribeMacro\glsxtrpl] +\cs{glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label} +\end{definition} +This is like \cs{glsxtr} but uses \cs{glspl} instead of \cs{gls}. + +\begin{definition}[\DescribeMacro\Glsxtr] +\cs{Glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label} +\end{definition} +This is like \cs{glsxtr} but uses \cs{Gls} instead of \cs{gls}. + +\begin{definition}[\DescribeMacro\Glsxtrpl] +\cs{Glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label} +\end{definition} +This is like \cs{glsxtr} but uses \cs{Glspl} instead of \cs{gls}. + +If you use UTF-8 and don't want the inconvenient of needing +to use an ASCII-only label, then it's better to use +\XeLaTeX\ or \LuaLaTeX\ instead of \LaTeX\ (or \pdfLaTeX). +If you really desperately want to use UTF-8 entry labels without +switching to \XeLaTeX\ or \LuaLaTeX\ then there is a starred +version of \cs{GlsXtrEnableOnTheFly} that allows you to +use UTF-8 characters in \meta{label}, but it's experimental and +may not work in some cases. + +\begin{important} +If you use the starred version of \cs{GlsXtrEnableOnTheFly} +don't use any commands in the \meta{label}, even if they expand +to just text. +\end{important} + +\chapter{\appfmt{bib2gls}: Managing Reference Databases} +\label{sec:bib2gls} + +There is a new command line application called +\gls{bib2gls}, which works in much the same way as +a combination of \appfmt{bibtex} and +\appfmt{makeindex}\slash\appfmt{xindy}. +Instead of storing all your entry definitions in a \texttt{.tex} and +loading them using \cs{input} or \cs{loadglsentries}, the entries +can instead be stored in a \texttt{.bib} file and \gls{bib2gls} can +selectively write the appropriate commands to a \texttt{.glstex} +file which is loaded using \cs{glsxtrresourcefile} (or +\cs{GlsXtrLoadResources}). + +This means that you can use a reference managing system, such as +JabRef, to maintain the database and it reduces the \TeX\ overhead +by only defining the entries that are actually required in the +document. If you currently have a \texttt{.tex} file that contains +hundreds of definitions, but you only use a dozen or so in your +document, then the build time is needlessly slowed by the unrequired +definitions that occur when the file is input. (You can convert an +existing \texttt{.tex} file containing glossary definitions to a +\texttt{.bib} file using \app{convertgls2bib}, supplied with +\gls{bib2gls}.) + +There are some new commands and options added to +\styfmt{glossaries-extra} to help assist the integration of +\gls{bib2gls} into the document build process. + +This chapter just provides a general overview of \gls{bib2gls}. +The full details and some sample documents are provided +in the \gls{bib2gls} \href{http://mirrors.ctan.org/support/bib2gls/bib2gls.pdf}{manual}. + +An example of the contents of \texttt{.bib} file that stores +glossary entries that can be extracted with \gls{bib2gls}: +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal}, + see={[see also]{duck,goose}} +} + +@entry{duck, + name={duck}, + description = {a waterbird with short legs} +} + +@entry{goose, + name="goose", + plural="geese", + description={a waterbird with a long neck} +} +\end{verbatim} + +The follow provides some abbreviations: +\begin{verbatim} +@string{ssi={server-side includes}} +@string{html={hypertext markup language}} + +@abbreviation{shtml, + short="shtml", + long= ssi # " enabled " # html, + description={a combination of \gls{html} and \gls{ssi}} +} + +@abbreviation{html, + short ="html", + long = html, + description={a markup language for creating web pages} +} + +@abbreviation{ssi, + short="ssi", + long = ssi, + description={a simple interpreted server-side scripting language} +} +\end{verbatim} + +Here are some symbols: +\begin{verbatim} +preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"} + +@symbol{M, + name={$\mtx{M}$}, + text={\mtx{M}}, + description={a matrix} +} + +@symbol{v, + name={$\vec{v}$}, + text={\vec{v}}, + description={a vector} +} + +@symbol{S, + name={$\mathcal{S}$}, + text={\mathcal{S}}, + description={a set} +} +\end{verbatim} + +To ensure that \gls{bib2gls} can find out which entries have been +used in the document, you need the \pkgopt{record} package option: +\begin{verbatim} +\usepackage[record]{glossaries-extra} +\end{verbatim} +If this option's value is omitted (as above), the normal indexing +will be switched off, since \gls{bib2gls} can also sort the entries and +collate the locations. + +If you still want to use an indexing application (for example, you +need a custom \gls{xindy} rule), then just use +\pkgopt[alsoindex]{record} and continue to use \cs{makeglossaries} +and \cs{printglossary} (or \cs{printglossaries}), but you also need +to instruct \gls{bib2gls} to omit sorting to save time and +to prevent the \gloskey{sort} key from being set. + +The \texttt{.glstex} file created by \gls{bib2gls} is loaded using: +\begin{definition}[\DescribeMacro\glsxtrresourcefile] +\cs{glsxtrresourcefile}\oarg{options}\marg{filename} +\end{definition} +(Don't include the file extension in \meta{filename}.) +There's a shortcut version (recommended over the above) that sets \meta{filename} to use \cs{jobname}: +\begin{definition}[\DescribeMacro\GlsXtrLoadResources] +\cs{GlsXtrLoadResources}\oarg{options} +\end{definition} +On the first use, this command is a shortcut for +\begin{alltt} +\cs{glsxtrresourcefile}\oarg{options}\{\cs{jobname}\} +\end{alltt} +On subsequent use,\footnote{Version 1.11 only allowed one use +of \cs{GlsXtrLoadResources} per document.}\ this command is a shortcut for +\begin{alltt} +\cs{glsxtrresourcefile}\oarg{options}\{\cs{jobname}-\meta{n}\} +\end{alltt} +where \meta{n} is the current value of +\begin{definition} +\cs{glsxtrresourcecount} +\end{definition} +which is incremented at the end of \cs{GlsXtrLoadResources}. +Any advisory notes regarding \cs{glsxtrresourcefile} also +apply to \cs{GlsXtrLoadResources}. + +The \cs{glsxtrresourcefile} command writes the line +\begin{alltt} +\cs{glsxtr@resource}\marg{options}\marg{filename} +\end{alltt} +to the \texttt{.aux} file and will input +\meta{filename}\texttt{.glstex} if it exists.\footnote{v1.08 assumed +\meta{filename}\texttt{.tex} but that's potentially dangerous if, +for example, \meta{filename} happens to be the same as \cs{jobname}. +The \texttt{.glstex} extension was enforced by version 1.11.} + +Since the \texttt{.glstex} file won't exist on the first \LaTeX\ run, the +\pkgopt{record} package option additionally switches on +\pkgopt[warn]{undefaction}. Any use of commands like \cs{gls} or +\cs{glstext} will produce ?? in the document, since the entries are +undefined at this point. Once \gls{bib2gls} has created the +\texttt{.glstex} file the references should be resolved. +This may cause a shift in the locations if the actual text produced +once the entry is defined is significantly larger than the +placeholder ?? (as this can alter the page breaking). + +Note that as from v1.12, \cs{glsxtrresourcefile} temporarily +switches the category code of \texttt{@} to 11 (letter) while it +reads the file to allow for any internal commands stored in the +location field. + +\section{Selection} + +The default behaviour is for \gls{bib2gls} to select all entries +that have a record in the \texttt{.aux} file, and any dependent +entries (including parent and cross-references). The +\texttt{glsignore} format (for example, +\verb|\gls[format=glsignore]{duck}|) is recognised by \gls{bib2gls} +as a special ignored record. This means that it will match +the selection criteria but the record won't be added to +the location list. This means that you won't get spurious +commas in the location list (as can happen with the other indexing +methods), so you can do, for example, +\begin{verbatim} +\GlsXtrSetDefaultNumberFormat{glsignore} +\end{verbatim} +at the start of the front matter and +\begin{verbatim} +\GlsXtrSetDefaultNumberFormat{glsnumberformat} +\end{verbatim} +at the start of the main matter to prevent any records in the +front matter from occurring in the location lists. + +\begin{important} +Note that commands like \cs{glsaddall} and \cs{glsaddallunused} don't work with \gls{bib2gls} as the command +has to iterate over the internal lists of defined entry labels, which will be empty on the first +run and on subsequent runs will only contain those entries that have +been selected by \gls{bib2gls}. +\end{important} + +If you want to add all +entries to the glossary, you need to tell \gls{bib2gls} this in the +options list. For example: +\begin{verbatim} +\GlsXtrLoadResources[src={terms},selection={all}] +\end{verbatim} +This will add all entries, regardless of whether or not they +have any records in the \texttt{.aux} file. Those that don't +have any records will have an empty location list. +See the \gls{bib2gls} user manual for more details of this option. + +\section{Sorting and Displaying the Glossary} + +There are many sorting options provided by \gls{bib2gls}. +The default is to sort according to the system locale. +If the document has a language setting, you can use +\texttt{sort=doc} to instruct \gls{bib2gls} to sort according to +that. (The language tag obtained from \sty{tracklang}'s +interface is written to the \texttt{.aux} file.) For a multilingual +document you need to explicitly set the locale using a well-formed +language tag. For example: +\begin{verbatim} +\GlsXtrLoadResources[ + src=terms, % data in terms.bib + sort=de-DE-1996 % sort according to this locale +] +\end{verbatim} +The locale-sensitive sort methods usually ignore most +punctuation so for lists of symbols you may find it more +appropriate to use one of the letter-base sort methods +that sort according to the Unicode value of each character. +Alternatively you can provide a custom rule. +See the \gls{bib2gls} manual for full details of all the available +sort methods. + +Since the \texttt{.glstex} file only defines those references +required +within the document (selected according to the \texttt{selection} +option) and the definitions have been written in the +order corresponding to \gls{bib2gls}['s] sorted list, the glossaries can +simply be displayed using \cs{printunsrtglossary} (or +\cs{printunsrtglossaries}), described in \sectionref{sec:printunsrt}. + +Suppose the \texttt{.bib} examples shown above have been stored in +the files \texttt{terms.bib}, \texttt{abbrvs.bib} and +\texttt{symbols.bib} which may either be in the current directory or +on \TeX's path. Then the document might look like: +\begin{verbatim} +\documentclass{article} + +\usepackage[record]{glossaries-extra} + +\setabbreviationstyle{long-short-desc} + +\GlsXtrLoadResources[src={terms,abbrvs,symbols}] + +\begin{document} +\gls{bird} + +\gls{shtml} + +\gls{M} + +\printunsrtglossaries +\end{document} +\end{verbatim} +The document build process (assuming the document is called +\texttt{mydoc}) is: +\begin{verbatim} +pdflatex mydoc +bib2gls mydoc +pdflatex mydoc +\end{verbatim} +This creates a single glossary containing the entries: +\texttt{bird}, \texttt{duck}, \texttt{goose}, +\texttt{html}, \texttt{M}, \texttt{shtml} and \texttt{ssi} (in that +order). The \texttt{bird}, \texttt{shtml} and \texttt{M} entries +were added because \gls{bib2gls} detected (from the \texttt{.aux} +file) that they had been used in the document. The other entries +were added because \gls{bib2gls} detected (from the \texttt{.bib} +files) that they are referenced by the used entries. In the case of +\texttt{duck} and \texttt{goose}, they are in the \gloskey{see} +field for \texttt{bird}. In the case of \texttt{ssi} and +\texttt{html}, they are referenced in the \gloskey{description} +field of \texttt{shtml}. These cross-referenced entries won't have a +location list when the glossary is first displayed, but depending on +how they are referenced, they may pick up a location list on the +next document build. + +The entries can be separated into different glossaries with +different sort methods: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,abbreviations,symbols]{glossaries-extra} + +\setabbreviationstyle{long-short-desc} + +\GlsXtrLoadResources[src={terms},sort={en-GB},type=main] + +\GlsXtrLoadResources + [src={abbrvs},sort={letter-nocase},type=abbreviations] + +\GlsXtrLoadResources + [src={symbols},sort={use},type={symbols}] + +\begin{document} +\gls{bird} + +\gls{shtml} + +\gls{M} + +\printunsrtglossaries +\end{document} +\end{verbatim} + +Or you can have multiple instance of \cs{GlsXtrLoadResources} +with the same \texttt{type}, which will produce a glossary +with ordered sub-blocks. For example: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,style=indexgroup]{glossaries-extra} + +\setabbreviationstyle{long-short-desc} + +\GlsXtrLoadResources + [src={abbrvs},sort={letter-nocase},type=main, + group={Abbreviations}] + +\GlsXtrLoadResources + [src={symbols},sort={use},type=main, + group={Symbols}] + +\GlsXtrLoadResources[src={terms},sort={en-GB},type=main] + +\begin{document} +\gls{bird} + +\gls{shtml} + +\gls{M} + +\printunsrtglossaries +\end{document} +\end{verbatim} +This will result in a glossary where the first group has +the title \qt{Abbreviations}, the second group has the +title \qt{Symbols} and then follow the usual letter groups. +Note that for this example to work, you must run \gls{bib2gls} +with the \verb|--group| (or \verb|-g|) switch. For example, +if the document is called \texttt{myDoc.tex}: +\begin{verbatim} +pdflatex myDoc +bib2gls -g myDoc +pdflatex myDoc +\end{verbatim} +The value of the \gloskey{group} field must always be a label. You +can set the corresponding title with \cs{glsxtrsetgrouptitle} +(see \sectionref{sec:glosstylemods}). If no title is set then the +label is used as the group title. + +You can provide your own custom sort rule. For example, +if you are using \XeLaTeX\ or \LuaLaTeX: +\begin{alltt} +\cs{GlsXtrLoadResources}[ + src=terms, % entries in terms.bib + sort=custom, % custom sort rule + sort-rule=\{% required with sort=custom + < \ae;\AE\ < a;\'a;\aa;\"a,\"A;\'A;\AA;\"A < b,B + < c;\'c,C;\'C < d,D < e;\'e,E;\'E < f,F < g,G + < h,H < i;\'i,I;\'I < j,J < l;\l,L;\L < m,M < n,N + < o;\"o;\o,O;\"O;\O\ < p,P < q,Q < r,R < s;\'s,S;\'S + < t,T < u;\'u,U;\'U < v,V < w,W < x,X < y,Y < + z;\.z,Z;\.Z + \} +] +\end{alltt} +Remember that if you are using \sty{inputenc} then extended +characters, such as \'e or \o, are active and will expand when +written to the \texttt{.aux} file. So with PDF\LaTeX\ the +above would have to be changed to protect against expansion. +Some of the options, including \texttt{sort-rule}, +allow Unicode characters to be indicated in the format +\cs{u}\meta{hex} (or \cs{u}~\meta{hex}) \textbf{in the \texttt{.aux} file}. \gls{bib2gls} +will recognise this as the character +given by the hexadecimal value \meta{hex}. The \cs{u} also needs +protection from expansion, so with a non-Unicode aware +engine, the character \ae\ needs to be written as +\texttt{\cs{string}\cs{u}E6} and so on. This is quite cumbersome, +but you can use the shortcut \texttt{\ics{glshex} E6} instead, so +the above needs to be written as: +\begin{alltt} +\cs{GlsXtrLoadResources}[ + src=terms, % entries in terms.bib + sort=custom, % custom sort rule + sort-rule=\{% required with sort=custom + < \cs{glshex} E6;\cs{glshex} C6 + < a;\cs{glshex} E1;\cs{glshex} E5,\cs{glshex} E4,A;\cs{glshex} C1;\cs{glshex} C5;\cs{glshex} C4 + < b,B < c;\cs{glshex} 0107,C;\cs{glshex} 0106 < d,D + < e;\cs{glshex} E9,E;\cs{glshex} C9 < f,F < g,G + < h,H < i;\cs{glshex} ED,I;\cs{glshex} CD < j,J + < l;\cs{glshex} 0142,L;\cs{glshex} 0141 < m,M < n,N + < o;\cs{glshex} F6;\cs{glshex} F8,O;\cs{glshex} D6;\cs{glshex} D8 + < p,P < q,Q < r,R < s;\cs{glshex} 013F,S;\cs{glshex} 015A + < t,T < u;\cs{glshex} FA,U;\cs{glshex} DA < v,V < w,W < x,X < y,Y + < z;\cs{glshex} 017C,Z;\cs{glshex} 017B + \}] +\end{alltt} + +\section{The \styfmt{glossaries-extra-bib2gls} package} +\label{sec:bib2glssty} + +The package option \pkgopt[only]{record} (or simply \pkgopt{record}) +automatically loads the supplementary package +\sty{glossaries-extra-bib2gls}, which provides some commands +that are specific to \gls{bib2gls}. The package isn't +loaded by \pkgopt[alsoindex]{record} as that option is intended +for sorting with \gls{makeindex} or \gls{xindy} and it is expected +that the sorting will be switched off (with the resource option +\texttt{sort=none}). + +If \sty{glossaries-extra-bib2gls} is loaded via the +\pkgopt{record} package option then the check for associated +language resource files (see \sectionref{sec:lang}) will also +search for the existence of +\texttt{glossariesxtr-}\meta{script}\texttt{.ldf} for each +document dialect (where \meta{script} is the four letter +script identifier, such as \texttt{Latn}). + +This package provides some shortcut commands that use +\ics{printunsrtglossary} if the relevant package option has defined +the associated glossary: \ics{printunsrtabbreviations}, +\ics{printunsrtacronyms}, \ics{printunsrtsymbols}, +\ics{printunsrtnumbers} and \ics{printunsrtindex}. + +\begin{definition}[\DescribeMacro\glsxtrprovidecommand] +\cs{glsxtrprovidecommand}\marg{cs}\oarg{n}\oarg{default}\marg{definition} +\end{definition} +This command is intended for use in \texttt{@preamble}. +It's simply defined to \cs{providecommand} in +\sty{glossaries-extra-bib2gls} but \gls{bib2gls}['s] interpreter +treats it as \cs{renewcommand}. This means that you can +override \gls{bib2gls}['s] internal definition of a command +without overriding the command definition in the document +(if it's already defined before the resource file is input). +For example +\begin{verbatim} +@preamble{"\glsxtrprovidecommand{\int}{integral}"} +\end{verbatim} +This will force \gls{bib2gls} to treat \cs{int} as the word +\qt{integral} to assist sorting but if this preamble code is written +to the \texttt{.glstex} file (as it is by default) then it won't +override the current definition (provided by the kernel or redefined +by a package). + +The helper commands in the resource files are defined using +\cs{providecommand}. For many of them, if you want to provide an +alternative definition then you need to define the command before +the resource file is loaded. There are a few that may be redefined +afterwards but if you use \cs{renewcommand} then you will get an +error on the first \LaTeX\ run when the \texttt{.glstex} file +doesn't exist. In this case, you may prefer to use: +\begin{definition}[\DescribeMacro\glsrenewcommand] +\cs{glsrenewcommand}\marg{cs}\oarg{n}\oarg{default}\marg{definition} +\end{definition} +This behaves like \cs{renewcommand} but only generates a warning +rather than an error if the command isn't already defined so it +won't interrupt the document build. + +\begin{definition}[\DescribeMacro\GlsXtrIndexCounterLink] +\cs{GlsXtrIndexCounterLink}\marg{text}\marg{label} +\end{definition} +If the \ics{hyperref} command has been defined (that is, +\sty{hyperref} has been loaded before \styfmt{glossaries-extra}) +then this command checks for the existence of the +\texttt{indexcounter} field. If this field is set for the entry +given by \meta{label}, this command does +\cs{hyperref}\texttt{[wrglossary.\meta{value}]\marg{text}}, where +\meta{value} is the value of the \texttt{indexcounter} field. If the +field isn't set or if \cs{hyperref} hasn't been defined, this just +does \meta{text}. This command is provided for use with the +\pkgopt{indexcounter} package option combined with \gls{bib2gls}['s] +\texttt{save-index-counter} resource option. See the \gls{bib2gls} +manual for further details (at least version 1.4). + +If you use the \texttt{set-widest} resource option, \gls{bib2gls} +v1.8+ will now use: +\begin{definition}[\DescribeMacro\glsxtrSetWidest] +\cs{glsxtrSetWidest}\marg{type}\marg{level}\marg{text} +\end{definition} +(if it has been defined) to set the widest name for the given +glossary type and level. This allows for both the \glostyle{alttree} +style and the styles provided by \sty{glossary-longextra}, which +need to know the widest name. + +If \gls{bib2gls} can't determine the widest name (typically because +the name field consists of commands that aren't recognised by the +interpreter) then \gls{bib2gls} v1.8+ will now use: +\begin{definition}[\DescribeMacro\glsxtrSetWidestFallback] +\cs{glsxtrSetWidestFallback}\marg{max depth}\marg{list} +\end{definition} +(if defined). Currently the maximum hierarchical depth \meta{max +depth} may only be 0 or 2. This command requires commands provided +by the \sty{glossaries-extra-stylemods} package with the +\glostyle{alttree} style enabled. In this case, it may be simpler +to just use \ics{glssetwidest}. + +\subsection{Supplemental Locations} +\label{sec:supplocations} + +\begin{definition}[\DescribeMacro\glsxtrdisplaysupploc] +\cs{glsxtrdisplaysupploc}\marg{prefix}\marg{counter}\marg{format}\marg{src}\marg{location} +\end{definition} +This is used by \gls{bib2gls} version 1.7+ for supplemental +locations, instead of using \cs{glsxtrsupphypernumber} with the +\catattr{externallocation} attribute. This command sets up the +location counter and prefix (used in the formation of hyperlinks) +and then uses +\begin{definition}[\DescribeMacro\glsxtrmultisupplocation] +\cs{glsxtrmultisupplocation}\marg{location}\marg{src}\marg{format} +\end{definition} +to format the actual location (with an external hyperlink, if +supported). + +\subsection{Nameref Record} +\label{sec:recordnameref} + +Normally locations are recorded in the \texttt{.aux} file +in the form: +\begin{definition} +\cs{glsxtr@record}\marg{label}\marg{prefix}\marg{counter}\marg{format}\marg{location} +\end{definition} +The \pkgopt[nameref]{record} option, which requires at least +\gls{bib2gls} v1.8, instead uses: +\begin{definition} +\cs{glsxtr@record@nameref}\marg{label}\marg{prefix}\marg{counter}\marg{format}\marg{location}\marg{title}\marg{href}\marg{hcounter} +\end{definition} +where \meta{title} is obtained from \cs{@currentlabelname} +and \meta{href} is obtained from \cs{@currentHref}. These +commands require \sty{hyperref}. If they are undefined, +\meta{title} and \meta{href} will be left empty and \gls{bib2gls} +will treat it as a regular record. + +\begin{important} +Be careful with this option as \meta{href} will globally change on every +instance of \cs{refstepcounter} but \meta{title} won't necessarily +change. It can therefore cause unexpected behaviour. +\end{important} + +The final argument \meta{hcounter} is obtained from +\cs{theH}\meta{counter} which provides the partial target name associated +with the indexing counter. With the original +\gls{makeindex}\slash \gls{xindy} approach, it's not possible to +include this information in the location, so the base +\sty{glossaries} package attempts to derive a prefix from which the +\meta{hcounter} value can be reconstituted by appending the prefix. +Unfortunately, not all definitions of \cs{theH}\meta{counter} are in +the form \meta{prefix}\cs{the}\meta{counter} (most notably the +\ctr{equation} counter with chapters) so this can fail. + +Since \gls{bib2gls} is customized specifically for use with +\styfmt{glossaries-extra}, it's now possible to save +\meta{hcounter}, so the \pkgopt[nameref]{record} option does this. +By providing both \meta{href} and \meta{hcounter}, you can determine +which target you would rather use. The default is to use +\meta{hcounter}, which will take you to the place where the +corresponding counter was incremented with \cs{refstepcounter}. +However, you may choose to switch to using the \meta{href} target, +which will take you to the nearest target before the indexing took +place. + +With \gls{bib2gls} v1.8+, normal locations are displayed using: +\begin{definition} +\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location} +\end{definition} +This is provided by the base \sty{glossaries} package and is simply +defined to do: +\begin{definition} +\cs{setentrycounter}\oarg{prefix}\marg{counter}\cs{csuse}\marg{format}\marg{location} +\end{definition} +Earlier versions of \gls{bib2gls} only used this in the +\gloskey{loclist} field and explicitly used \cs{setentrycounter} in +the \gloskey{location} field followed by +\cs{}\meta{format}\marg{location}, which follows the code that's created +with the default \pkgopt{makeindex} setting. +The \cs{setentrycounter} command sets up the prefix needed for +\cs{glshypernumber} to reform the target name from the given +location. + +The locations identified by \cs{glsxtr@record@nameref} are written +by \gls{bib2gls} to the location list using: +\begin{definition}[\DescribeMacro\glsxtrdisplaylocnameref] +\cs{glsxtrdisplaylocnameref}\marg{prefix}\marg{counter}\marg{format}\marg{location}\marg{title}\marg{href}\marg{hcounter}\marg{file} +\end{definition} +With normal internal locations, \meta{file} will always be empty. +With supplemental locations, \meta{file} will be the external file +reference. + +The default definition is: +\begin{verbatim} +\newcommand*{\glsxtrdisplaylocnameref}[8]{% + \ifstrequal{#2}{equation}% + {\glsxtrnamereflink{#3}{(#4)}{#2.#7}{#8}}% + {% + \ifstrempty{#5}% + {% + \glsxtrnamereflink{#3}{#4}{#2.#7}{#8}% + }% + {% + \ifstrequal{#2}{page}% + {\glsxtrnamereflink{#3}{#4}{#2.#7}{#8}}% + {\glsxtrnamereflink{#3}{#5}{#2.#7}{#8}}% + }% + }% +} +\end{verbatim} +which uses: +\begin{definition}[\DescribeMacro\glsxtrnamereflink] +\cs{glsxtrnamereflink}\marg{format}\marg{title}\marg{target}\marg{file} +\end{definition} +This ignores the \meta{prefix}, \meta{counter} and \marg{location} +arguments and instead creates a hyperlink with the target name obtained from \meta{target} (and \meta{file}, if not empty). + +Since pages and equations typically don't have titles, the default +definition of \cs{glsxtrdisplaylocnameref} checks the counter was +used as the location. If it's \ctr{page} or if \meta{title} is empty, then just the location is +used as the hyperlink text. If the counter \ctr{equation}, then the +text is the location in parentheses. Otherwise the text is obtained +from \meta{title}. + +If \meta{file} is empty an internal link is created with: +\begin{definition}[\DescribeMacro\glsxtrfmtinternalnameref] +\cs{glsxtrfmtinternalnameref}\marg{target}\marg{format}\marg{title} +\end{definition} +otherwise an external link is created with: +\begin{definition}[\DescribeMacro\glsxtrfmtexternalnameref] +\cs{glsxtrfmtexternalnameref}\marg{target}\marg{format}\marg{title}\marg{file} +\end{definition} +The \meta{file} argument is set by \gls{bib2gls} for supplemental +locations. + +Here's alternative definition that uses the \meta{prefix} and +\meta{counter} to reform the target name (as +\cs{glsnoidxdisplayloc}) but uses the \meta{title} as the hyperlink text: +\begin{verbatim} +\renewcommand*{\glsxtrdisplaylocnameref}[7]{% + \glsxtrnamereflink{#3}{#5}{#6}{#7}% +} +\end{verbatim} +which uses: +\begin{definition}[\DescribeMacro\glsxtrnameloclink] +\cs{glsxtrnameloclink}\marg{prefix}\marg{counter}\marg{format}\marg{location}\marg{title}\marg{file} +\end{definition} +This uses the same commands as \cs{glsxtrnamereflink} +to produce the hyperlinks. + +In both cases, the link is encapsulated with the text-block command +whose name is given by \meta{format}, but \cs{glshypernumber} is +first locally redefined to \cs{@firstofone} to prevent a conflict with the +usual location hyperlink formation. This means that if the +\meta{format} is \texttt{hyperbf} then it will simply behave like +\texttt{textbf}. + +For compactness, \gls{bib2gls} merges normal records if the +\meta{prefix}, \meta{counter} and \meta{location} all match. (An +order of precedence can be provided for format conflicts.) With +nameref records, you can use the \verb|--merge-nameref-on| switch +provided by \gls{bib2gls} v1.8+ to determine how to merge nameref +records. This switch must be followed by one of the following +keywords: \texttt{hcounter} (merge on \meta{hcounter}, default) +\texttt{href} (merge on \meta{href}), \texttt{title} (merge +on \meta{title}) and \texttt{location} (merge on \meta{location}, as +regular records). In all cases, the \meta{counter} must also match. + +\subsection{Helper Commands for Resource Options} +\label{sec:resourcecommands} + +\begin{definition}[\DescribeMacro\glshex] +\cs{glshex} +\end{definition} +This is just defined as \verb|\string\u|, which is required +when you need to indicate a Unicode character in the form +\cs{u}\meta{hex} in some of +the resource options (as illustrated above). + +\begin{definition}[\DescribeMacro\glscapturedgroup] +\cs{glscapturedgroup} +\end{definition} +This is just defined as \verb|\string\$| and is used for +the captured group reference in a replacement part of a regular +expression substitution (requires at least \gls{bib2gls} version 1.5). For example: +\begin{verbatim} +sort-replace={{([a-zA-Z])\string\.}{\glscapturedgroup1}} +\end{verbatim} +This only removes a full stop that follows any of the characters +a,\ldots,z or A,\ldots,Z. + +If you use the \texttt{save-child-count} resource option, +you can test if the \texttt{childcount} field is non-zero using: +\begin{definition}[\DescribeMacro{\GlsXtrIfHasNonZeroChildCount}] +\cs{GlsXtrIfHasNonZeroChildCount}\marg{label}\marg{true}\marg{false} +\end{definition} +This internally uses \cs{GlsXtrIfFieldNonZero} and will do +\meta{false} if the field isn't set. Within \meta{true} and +\meta{false} you can use \cs{glscurrentfieldvalue} to access the +value. (It will be 0 in \meta{false} if the field isn't set.) + + +A convenient shortcut for use in the \texttt{entry-type-aliases} +setting: +\begin{definition}[\DescribeMacro\GlsXtrBibTeXEntryAliases] +\cs{GlsXtrBibTeXEntryAliases} +\end{definition} +This provides aliases for Bib\TeX's standard entry types to +\gls{bib2gls}['s] \texttt{@bibtexentry} entry type (requires at +least \gls{bib2gls} version 1.4). + +You may also want to provide storage keys for Bib\TeX's standard +fields rather than having to alias them all. This can be done with: +\begin{definition}[\DescribeMacro\GlsXtrProvideBibTeXFields] +\cs{GlsXtrProvideBibTeXFields} +\end{definition} +Note that Bib\TeX's \texttt{type} field clashes with the \sty{glossaries} +package's \gloskey{type} key, so this command provides the key +\texttt{bibtextype} instead. You can alias it with +\texttt{field-aliases={type=bibtextype}} in the resource options. +Each storage key is provided with a convenient command to access the +value in the form \cs{glsxtrbib}\meta{field}. For example, +\cs{glsxtrbibaddress}. The \texttt{bibtextype} field can be accessed +with \cs{glsxtrbibtype}. Each of these commands takes the entry +label as the sole argument. + +The \sty{glossaries-extra-bib2gls} package also provides definitions +of the missing mathematical Greek commands: \ics{Alpha}, +\ics{Beta}, \ics{Epsilon}, \ics{Zeta}, \ics{Eta}, \ics{Iota}, +\ics{Kappa}, \ics{Mu}, \ics{Nu}, \ics{Omicron}, \ics{Rho}, +\ics{Tau}, \ics{Chi}, \ics{Digamma}, \ics{omicron}. +These are all defined with \cs{providecommand}, so they won't override +any definitions provided by any package loaded before +\sty{glossaries-extra}. Since \gls{bib2gls}['s] interpreter +recognises these commands, using them instead of explicitly using +the Latin characters with the same shape helps to keep the Greek +symbols together when sorting. +Similarly, if \sty{upgreek} has been loaded, the missing upright +Greek commands are also provided. + +The remaining commands provide common rule blocks for use in +the \texttt{sort-rule} resource option. If you want a rule for +a specific locale, you can provide similar commands in a file called +\texttt{glossariesxtr-}\meta{tag}\texttt{.ldf}, where \meta{tag} +identifies the dialect, locale, region or root language. See the +description of \cs{IfTrackedLanguageFileExists} in the +\sty{tracklang} documentation for further details. If this file is +on \TeX's path and the \sty{tracklang} package (automatically loaded +by \styfmt{glossaries}) detects that the document has requested that +language or locale, then the file will automatically be loaded. +For example, if you want to provide a rule block for Welsh, then +create a file called \texttt{glossariesxtr-welsh.ldf} that contains: +\begin{verbatim} +\ProvidesGlossariesExtraLang{welsh}[2018/02/23 v1.0] + +\@ifpackageloaded{glossaries-extra-bib2gls} +{ + \newcommand{\glsxtrWelshRules}{% + \glsxtrLatinA + \string<b,B + \string<c,C + \string<ch,CH + \string<d,D + \string<dd,DD + \string<\glsxtrLatinE + \string<f,F + \string<ff,FF + \string<g,G + \string<ng,NG + \string<\glsxtrLatinH + \string<\glsxtrLatinI + \string<j,J + \string<\glsxtrLatinL + \string<ll,LL + \string<\glsxtrLatinM + \string<\glsxtrLatinN + \string<\glsxtrLatinO + \string<\glsxtrLatinP + \string<ph,PH + \string<r,R + \string<rh,RH + \string<\glsxtrLatinS + \string<\glsxtrLatinT + \string<th,TH + \string<u,U + \string<w,W + \string<y,Y + } +} +{}% glossaries-extra-bib2gls.sty not loaded +\end{verbatim} +(The use of \cs{string} is in case the \texttt{<} character +has been made active.) You can provide more than one rule-block +per local, to allow for loanwords or foreign words. For example, +you could provide \cs{glsxtrWelshIRules}, \cs{glsxtrWelshIIRules} +etc. + +If the rules are for a particular script (independent of language +or region) then they can be provided in a file given by +\texttt{glossariesxtr-}\meta{script}\texttt{.ldf} instead. For +example, the file \texttt{glossariesxtr-Cyrl.ldf} could contain: +\begin{verbatim} +\ProvidesGlossariesExtraLang{Cyrl}[2018/02/23 v1.0] +\newcommand*{\glsxtrGeneralCyrillicIRules}{% + % Cyrillic rules +} +\newcommand*{\glsxtrGeneralCyrillicIIRules}{% + % an alternative set of Cyrillic rules +} +\end{verbatim} +(Remember that the required document language scripts need to be tracked +through the \sty{tracklang} package, in order for these files to be +automatically loaded. This essentially means ensuring you load the +appropriate language package before \sty{tracklang} is loaded by +the base \sty{glossaries} package or any other package that uses it. +See the \sty{tracklang} documentation for further details.) + +Alternatively, if the rules are specific to a subject rather than +a region or language, then you can provide a supplementary +package. For example, if you have a package called, say, +\styfmt{mapsymbols} that provides map symbols, then the file +\texttt{mapsymbols.sty} might contain: +\begin{verbatim} +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{mapsymbols} +% some package or font loading stuff here to provide +% the appropriate symbols +\newcommand{\Stadium}{...} +\newcommand{\Battlefield}{...} +\newcommand{\Harbour}{...} +% etc + +% Provide a rule block: +\newcommand{\MapSymbolOrder}{% + \glshex 2694 % crossed-swords 0x2694 + \string< \glshex 2693 % anchor 0x2693 + \string< \glshex 26BD % football 0x26BD +} +\end{verbatim} +and the supplementary file \texttt{mapsymbols.bib} can provide +the appropriate definitions for \gls{bib2gls}: +\begin{verbatim} +@preamble{"\glsxtrprovidecommand{\Harbour}{\char"2693} +\glsxtrprovidecommand{\Battlefield}{\char"2694} +\glsxtrprovidecommand{\Stadium}{\char"26BD}"} +\end{verbatim} +Now both the preamble and rule block can be used in the resource +set: +\begin{verbatim} +\usepackage{mapsymbols}% my custom package +\usepackage[record]{glossaries-extra} + +\GlsXtrLoadResources[ + src={mapsymbols,% <--- my custom mapsymbols.bib + entries% data in entries.bib + }, + sort={custom}, + sort-rule={\glsxtrcontrolrules % control codes + ;\glsxtrspacerules % space characters + ;\glsxtrnonprintablerules % non-printable characters + ;\glsxtrcombiningdiacriticrules % combining diacritics + ,\glsxtrhyphenrules % hyphens + <\glsxtrgeneralpuncrules % general punctuation + <\glsxtrdigitrules % 0, ..., 9 + <\glsxtrfractionrules % fraction symbols + <\MapSymbolOrder % <--- custom map symbols + <\glsxtrMathItalicGreekIrules % math-greek symbols + <\glsxtrGeneralLatinIrules % Latin letters + } +] +\end{verbatim} + +The following commands are provided by +\sty{glossaries-extra-bib2gls}. They should be separated by +the rule separator characters \texttt{;}~(semi-colon) or \texttt{,}~(comma) +or \verb|&|~(ampersand) or \texttt{<}~(less than). See Java's +\href{http://docs.oracle.com/javase/8/docs/api/java/text/RuleBasedCollator.html}{Rule\-Based\-Collator} +documentation for details of the rule syntax. + +For example, the following will place the mathematical Greek +symbols (\ics{alpha}, \ics{Alpha}, \ics{beta}, \ics{Beta} etc) +in a block before Latin characters: +\begin{verbatim} +sort-rule={\glsxtrcontrolrules + ;\glsxtrspacerules + ;\glsxtrnonprintablerules + ;\glsxtrcombiningdiacriticrules + ,\glsxtrhyphenrules + <\glsxtrgeneralpuncrules + <\glsxtrdigitrules + <\glsxtrfractionrules + <\glsxtrMathItalicGreekIrules + <\glsxtrGeneralLatinIVrules + <\glsxtrLatinAA + <\glsxtrLatinOslash +} +\end{verbatim} + +\begin{definition}[\DescribeMacro\glsxtrcontrolrules] +\cs{glsxtrcontrolrules} +\end{definition} +These are control characters that are usually placed at the start of +a rule in the ignored section. They typically won't occur in +any sort values, but if they do they should normally be ignored. + +\begin{definition}[\DescribeMacro\glsxtrspacerules] +\cs{glsxtrspacerules} +\end{definition} +These are space characters. They typically come after the control +characters with the two blocks separated by a \texttt{;}~(semi-colon). + +\begin{definition}[\DescribeMacro\glsxtrnonprintablerules] +\cs{glsxtrnonprintablerules} +\end{definition} +These are non-printable characters (BOM, tabs, line feed and +carriage return). They typically come after the spaces separated by +a \texttt{;}~(semi-colon). These characters aren't checked for by +\gls{bib2gls} when it determines whether or not to use the +interpreter, so a~TAB or newline character may end up in the sort +value if it wasn't interpreted. + +\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticrules] +\cs{glsxtrcombiningdiacriticrules} +\end{definition} +These are combining diacritic marks which typically follow +the space and non-printable blocks (separated by a semi-colon). This command is +defined in terms of sub-block commands: +\begin{verbatim} +\newcommand*{\glsxtrcombiningdiacriticrules}{% + \glsxtrcombiningdiacriticIrules\string; + \glsxtrcombiningdiacriticIIrules\string; + \glsxtrcombiningdiacriticIIIrules\string; + \glsxtrcombiningdiacriticIVrules +} +\end{verbatim} +If you prefer, you can use the sub-blocks directly in your +required ordered. + +\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticIrules] +\cs{glsxtrcombiningdiacriticIrules} +\end{definition} +This contains the combining diacritics: acute, grave, breve, +circumflex, caron, ring, vertical line above, diaeresis (umlaut), +double acute, tilde, dot above, combining macron. + +\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticIIrules] +\cs{glsxtrcombiningdiacriticIIrules} +\end{definition} +This contains the combining diacritics: short solidus overlay, +cedilla, ogonek, dot below, low line, overline, hook above, +double vertical line above, double grave accent, candrabindu, +inverted breve, turned comma above, comma above, reversed comma +above, comma above right, grave accent below, acute accent below. + +\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticIIIrules] +\cs{glsxtrcombiningdiacriticIIIrules} +\end{definition} +This contains the combining diacritics: left tack below, right tack +below, left angle above, horn, left half ring below, up tack below, +down tack below, plus sign below, minus sign below, palatalized hook +below, retroflex hook below, diaresis below, ring below, comma +below, vertical line below, bridge below, inverted double arch +below, caron below, circumflex accent below, breve below, inverted +breve below, tilde below, macron below, double low line, tilde +overlay, short stroke overlay, long stroke overlay, long solidus +overlay, right half ring below, inverted bridge below, square below, +seagull below, x above, vertical tilde, double overline, Greek +perispomeni, Greek dialytika tonos, Greek ypogegrammeni, double +tilde, double inverted breve, Cyrillic titlo, Cyrillic +palatalization, Cyrillic dasia pneumata, Cyrillic psili pneumata. + +\begin{definition}[\DescribeMacro\glsxtrcombiningdiacriticIVrules] +\cs{glsxtrcombiningdiacriticIVrules} +\end{definition} +This contains the combining diacritics: +left harpoon above, right harpoon above, long vertical line overlay, +short vertical line overlay, anticlockwise arrow above, clockwise +arrow above, left arrow above, right arrow above, ring overlay, +clockwise ring overlay, anticlockwise ring overlay, three dots +above, four dots above, enclosing circle, enclosing square, +enclosing diamond, enclosing circle backslash, left right arrow +above. + +\begin{definition}[\DescribeMacro\glsxtrhyphenrules] +\cs{glsxtrhyphenrules} +\end{definition} +This contains hyphens (including the minus sign 0x2212). This rule +block typically comes after the diacritic rules separated by a +comma. + +\begin{definition}[\DescribeMacro\glsxtrgeneralpuncrules] +\cs{glsxtrgeneralpuncrules} +\end{definition} +This contains punctuation characters. This rule +block typically comes after the hyphen rules separated by a +less than (\texttt{<}). As with the combining diacritics, this +command is defined in terms of sub-blocks which may be used directly +instead if a different order is required: +\begin{verbatim} +\newcommand*{\glsxtrgeneralpuncrules}{% + \glsxtrgeneralpuncIrules + \string<\glsxtrcurrencyrules + \string<\glsxtrgeneralpuncIIrules +} +\end{verbatim} + +\begin{definition}[\DescribeMacro\glsxtrgeneralpuncIrules] +\cs{glsxtrgeneralpuncIrules} +\end{definition} +This is the first punctuation sub-block containing: +underscore, macron, comma, semi-colon, colon, exclamation mark, +inverted exclamation mark, question mark, inverted question mark, +solidus, full stop, acute accent, grave accent, circumflex accent, +diaersis, tilde, middle dot, cedilla, straight apostrophe, straight +double quote, left guillemet, right guillemet, left parenthesis, +right parenthesis, left square bracket, right square bracket, left +curly bracket, right curly bracket, section sign, pilcrow sign, +copyright sign, registered sign, at sign. + +\begin{definition}[\DescribeMacro\glsxtrcurrencyrules] +\cs{glsxtrcurrencyrules} +\end{definition} +This sub-block contains some currency symbols: +currency sign, Thai currency symbol baht, cent sign, colon sign, +cruzeiro sign, dollar sign, dong sign, euro sign, French franc sign, +lira sign, mill sign, naira sign, peseta sign, pound sign, rupee +sign, new sheqel sign, won sign, yen sign. + +\begin{definition}[\DescribeMacro\glsxtrgeneralpuncIIrules] +\cs{glsxtrgeneralpuncIIrules} +\end{definition} +This sub-block contains some other punctuation symbols: +asterisk, backslash, ampersand, hash sign, percent sign, plus sign, +plus-minus sign, division sign, multiplication sign, less-than sign, +equals sign, greater-than sign, not sign, vertical bar (pipe), +broken bar, degree sign, micron sign. + +\begin{definition}[\DescribeMacro\glsxtrdigitrules] +\cs{glsxtrdigitrules} +\end{definition} +This rule block contains the Basic Latin digits (0, \ldots, 9) +and the subscript and superscript digits (\textsubscript{0} +\textsuperscript{0} etc) made equivalent to the +corresponding Basic Latin digit. The digit block typically +comes after the punctuation rules separated by a less than +(\texttt{<}). + +\begin{definition}[\DescribeMacro\glsxtrBasicDigitrules] +\cs{glsxtrBasicDigitrules} +\end{definition} +This rule block contains just the Basic Latin digits (0, \ldots, 9). + +\begin{definition}[\DescribeMacro\glsxtrSubScriptDigitrules] +\cs{glsxtrSubScriptDigitrules} +\end{definition} +This rule block contains just the subscript digits +(\textsubscript{0} \ldots\ \textsubscript{9}). + +\begin{definition}[\DescribeMacro\glsxtrSuperScriptDigitrules] +\cs{glsxtrSuperScriptDigitrules} +\end{definition} +This rule block contains just the superscript digits +(\textsuperscript{0} \ldots\ \textsuperscript{9}). + +\begin{definition}[\DescribeMacro\glsxtrfractionrules] +\cs{glsxtrfractionrules} +\end{definition} +This rule block contains vulgar fraction characters. The digit block +typically comes after the digit rules separated by a less than +(\texttt{<}). + +There are a number of Latin rule blocks. Some of these included +extended characters or ligatures (such as \ss\ or \oe) but they don't +include accented characters. If you require a Latin rule block +that includes accented characters, digraphs, trigraphs or +other extended characters, then it's best to provide +similar commands in a \texttt{glossariesxtr-}\meta{tag}\texttt{.ldf} +file for the particular language or region. + +\begin{definition}[\DescribeMacro\glsxtrGeneralLatinIrules] +\cs{glsxtrGeneralLatinIrules} +\end{definition} +This is just the basic (non-extended) Latin alphabet with the superscript +and subscript Latin letters (\textsuperscript{a} \textsubscript{a} +etc) treated as the equivalent basic Latin letter. (If you don't +want the subscripts and superscripts included you can redefine +\cs{glsxtrLatinA} etc to omit them.) + +\begin{definition}[\DescribeMacro\glsxtrGeneralLatinIIrules] +\cs{glsxtrGeneralLatinIIrules} +\end{definition} +This is like \cs{glsxtrGeneralLatinIrules} but it includes eth +(Ð) between `D' and `E' and eszett (\ss) treated as `ss'. + +\begin{definition}[\DescribeMacro\glsxtrGeneralLatinIIIrules] +\cs{glsxtrGeneralLatinIIIrules} +\end{definition} +This is like \cs{glsxtrGeneralLatinIrules} but it includes eth +(Ð) between `D' and `E' and eszett (\ss) treated as `sz'. + +\begin{definition}[\DescribeMacro\glsxtrGeneralLatinIVrules] +\cs{glsxtrGeneralLatinIVrules} +\end{definition} +This is like \cs{glsxtrGeneralLatinIrules} but it includes eth +(Ð) between `D' and `E', ae-ligature (\ae) is treated as `ae', +oe-ligature (\oe) is treated as `oe', eszett (\ss) treated as `ss' +and thorn (þ) is treated as `th'. + +\begin{definition}[\DescribeMacro\glsxtrGeneralLatinVrules] +\cs{glsxtrGeneralLatinVrules} +\end{definition} +This is like \cs{glsxtrGeneralLatinIrules} but it includes eth +(Ð) between `D' and `E', eszett (\ss) treated as `ss' +and thorn (þ) treated as `th'. + +\begin{definition}[\DescribeMacro\glsxtrGeneralLatinVIrules] +\cs{glsxtrGeneralLatinVIrules} +\end{definition} +This is like \cs{glsxtrGeneralLatinIrules} but it includes eth +(Ð) between `D' and `E', eszett (\ss) treated as `sz' +and thorn (þ) treated as `th'. + +\begin{definition}[\DescribeMacro\glsxtrGeneralLatinVIIrules] +\cs{glsxtrGeneralLatinVIIrules} +\end{definition} +This is like \cs{glsxtrGeneralLatinIrules} but it includes +ae-ligature (\ae) between `A' and `B', eth (Ð) between `D' and +`E', insular G (Ᵹ) instead of `G', oe-ligature between `O' and `P', +long~s (ſ) equivalent to `s', thorn (þ) between `T' and `U' and wynn (Ƿ) +instead of W. + +\begin{definition}[\DescribeMacro\glsxtrGeneralLatinVIIIrules] +\cs{glsxtrGeneralLatinVIIIrules} +\end{definition} +This is like \cs{glsxtrGeneralLatinIrules} but ae-ligature (\ae) is treated as `ae', +oe-ligature (\oe) is treated as `oe', eszett (\ss) treated as `ss', +thorn (þ) is treated as `th', \O\ is treated as `O' and +`\L' is treated as `L'. + +\begin{definition}[\DescribeMacro\glsxtrLatinA] +\cs{glsxtrLatinA} +\end{definition} +A mini-rule that just covers `A' but includes the sub- and +superscript A. + +\begin{definition}[\DescribeMacro\glsxtrLatinE] +\cs{glsxtrLatinE} +\end{definition} +A mini-rule that just covers `E' but includes the +subscript E. + +\begin{definition}[\DescribeMacro\glsxtrLatinH] +\cs{glsxtrLatinH} +\end{definition} +A mini-rule that just covers `H' but includes the +subscript H. + +\begin{definition}[\DescribeMacro\glsxtrLatinK] +\cs{glsxtrLatinK} +\end{definition} +A mini-rule that just covers `K' but includes the +subscript K. + +\begin{definition}[\DescribeMacro\glsxtrLatinI] +\cs{glsxtrLatinI} +\end{definition} +A mini-rule that just covers `I' but includes the +superscript I. + +\begin{definition}[\DescribeMacro\glsxtrLatinL] +\cs{glsxtrLatinL} +\end{definition} +A mini-rule that just covers `L' but includes the +subscript L. + +\begin{definition}[\DescribeMacro\glsxtrLatinM] +\cs{glsxtrLatinM} +\end{definition} +A mini-rule that just covers `M' but includes the +subscript M. + +\begin{definition}[\DescribeMacro\glsxtrLatinN] +\cs{glsxtrLatinN} +\end{definition} +A mini-rule that just covers `N' but includes the +sub- and superscript N. + +\begin{definition}[\DescribeMacro\glsxtrLatinO] +\cs{glsxtrLatinO} +\end{definition} +A mini-rule that just covers `O' but includes the +sub- and superscript O. + +\begin{definition}[\DescribeMacro\glsxtrLatinP] +\cs{glsxtrLatinP} +\end{definition} +A mini-rule that just covers `P' but includes the +subscript P. + +\begin{definition}[\DescribeMacro\glsxtrLatinS] +\cs{glsxtrLatinS} +\end{definition} +A mini-rule that just covers `S' but includes the +subscript S. + +\begin{definition}[\DescribeMacro\glsxtrLatinT] +\cs{glsxtrLatinT} +\end{definition} +A mini-rule that just covers `T' but includes the +subscript T. + +\begin{definition}[\DescribeMacro\glsxtrLatinX] +\cs{glsxtrLatinX} +\end{definition} +A mini-rule that just covers `X' but includes the +subscript X. + +\begin{definition}[\DescribeMacro\glsxtrLatinEszettSs] +\cs{glsxtrLatinEszettSs} +\end{definition} +A mini-rule that just covers eszett (\ss) and makes long~s (ſ) followed +by short `s' equivalent to `\ss'. (This is used in the above blocks +that treat `\ss' as `ss'.) + +\begin{definition}[\DescribeMacro\glsxtrLatinEszettSz] +\cs{glsxtrLatinEszettSz} +\end{definition} +A mini-rule that just covers eszett (\ss) and makes long~s (ſ) followed +by `z' equivalent to `\ss'. (This is used in the above blocks +that treat `\ss' as `sz'.) + +\begin{definition}[\DescribeMacro\glsxtrLatinEth] +\cs{glsxtrLatinEth} +\end{definition} +A mini-rule for eth (Ð) so you don't need to remember the +Unicode values. + +\begin{definition}[\DescribeMacro\glsxtrLatinThorn] +\cs{glsxtrLatinThorn} +\end{definition} +A mini-rule for thorn (þ) so you don't need to remember the +Unicode values. + +\begin{definition}[\DescribeMacro\glsxtrLatinAELigature] +\cs{glsxtrLatinAELigature} +\end{definition} +A mini-rule for ae-ligature (\ae) so you don't need to remember the +Unicode values. + +\begin{definition}[\DescribeMacro\glsxtrLatinOELigature] +\cs{glsxtrLatinOELigature} +\end{definition} +A mini-rule for oe-ligature (\oe) so you don't need to remember the +Unicode values. + +\begin{definition}[\DescribeMacro\glsxtrLatinOslash] +\cs{glsxtrLatinOslash} +\end{definition} +A mini-rule for `\O' so you don't need to remember the +Unicode values. + +\begin{definition}[\DescribeMacro\glsxtrLatinLslash] +\cs{glsxtrLatinLslash} +\end{definition} +A mini-rule for `\L' so you don't need to remember the +Unicode values. + +\begin{definition}[\DescribeMacro\glsxtrLatinWynn] +\cs{glsxtrLatinWynn} +\end{definition} +A mini-rule for wynn (Ƿ) so you don't need to remember the +Unicode values. + +\begin{definition}[\DescribeMacro\glsxtrLatinInsularG] +\cs{glsxtrLatinInsularG} +\end{definition} +A mini-rule for insular G (Ᵹ) so you don't need to remember the +Unicode values. + +\begin{definition}[\DescribeMacro\glsxtrLatinSchwa] +\cs{glsxtrLatinSchwa} +\end{definition} +A mini-rule that just covers schwa (Ə) but includes the +subscript schwa. (Not used in any of the provided Latin rule blocks +described above.) + +\begin{definition}[\DescribeMacro\glsxtrLatinAA] +\cs{glsxtrLatinAA} +\end{definition} +A mini-rule for `\AA' so you don't need to remember the +Unicode values. (Not used in any of the provided Latin rule blocks +described above.) + +\begin{definition}[\DescribeMacro\glsxtrMathGreekIrules] +\cs{glsxtrMathGreekIrules} +\end{definition} +A rule block for mathematical Greek (\ics{alpha}, \ics{beta} etc) +and upright Greek (\ics{upalpha}, etc, from the \sty{upgreek} +package) characters that includes digamma (\ics{digamma} and +\ics{Digamma}) between epsilon and zeta. The upright and italic +versions are gathered together into the same letter group. + +\begin{definition}[\DescribeMacro\glsxtrMathGreekIIrules] +\cs{glsxtrMathGreekIIrules} +\end{definition} +As \cs{glsxtrMathGreekIrules} but doesn't include digamma. + +\begin{definition}[\DescribeMacro\glsxtrMathUpGreekIrules] +\cs{glsxtrMathUpGreekIrules} +\end{definition} +A rule block for upright Greek (\ics{upalpha}, etc, from +the \sty{upgreek} package) +characters that includes digamma (\ics{digamma} and \ics{Digamma}) +between epsilon and zeta. + +\begin{definition}[\DescribeMacro\glsxtrMathUpGreekIIrules] +\cs{glsxtrMathUpGreekIIrules} +\end{definition} +A rule block for upright Greek (\ics{upalpha}, etc, from +the \sty{upgreek} package) that doesn't include digamma. + +\begin{definition}[\DescribeMacro\glsxtrMathItalicGreekIrules] +\cs{glsxtrMathItalicGreekIrules} +\end{definition} +A rule block for mathematical Greek (\ics{alpha}, \ics{Alpha}, etc) +characters that includes digamma (\ics{diagamma} and \ics{Digamma}) +between epsilon and zeta. Note that even though the upper case +\cs{Delta} etc are actually rendered upright by \LaTeX, +\gls{bib2gls}['s] interpreter treats them as italic to help keep +them close to the lower case versions. + +\begin{definition}[\DescribeMacro\glsxtrMathItalicGreekIIrules] +\cs{glsxtrMathItalicGreekIIrules} +\end{definition} +A rule block for mathematical Greek (\ics{alpha}, \ics{Alpha}, etc) +characters that doesn't include digamma. + +\begin{definition}[\DescribeMacro\glsxtrMathItalicUpperGreekIrules] +\cs{glsxtrMathItalicUpperGreekIrules} +\end{definition} +A rule block for upper case mathematical Greek (\ics{Alpha}, +\ics{Beta}, etc) characters that includes digamma (\ics{Digamma}) +between epsilon and zeta. + +\begin{definition}[\DescribeMacro\glsxtrMathItalicUpperGreekIIrules] +\cs{glsxtrMathItalicUpperGreekIIrules} +\end{definition} +A rule block for upper case mathematical Greek (\ics{Alpha}, +\ics{Beta}, etc) characters that doesn't include digamma. + +\begin{definition}[\DescribeMacro\glsxtrMathItalicLowerGreekIrules] +\cs{glsxtrMathItalicLowerGreekIrules} +\end{definition} +A rule block for lower case mathematical Greek (\ics{alpha}, +\ics{beta}, etc) characters that includes digamma (\ics{digamma}) +between epsilon and zeta. + +\begin{definition}[\DescribeMacro\glsxtrMathItalicLowerGreekIIrules] +\cs{glsxtrMathItalicLowerGreekIIrules} +\end{definition} +A rule block for lower case mathematical Greek (\ics{alpha}, +\ics{beta}, etc) characters that doesn't include digamma. + +Additionally, there are commands in the form \cs{glsxtrUpAlpha}, +\cs{glsxtrUpBeta} etc and \cs{glsxtrMathItalicAlpha}, +\cs{glsxtrMathItalicBeta} etc +that just cover the upper and lower case forms of a special +Greek character (\cs{Upalpha}, \cs{upalpha} etc and \cs{Alpha}, +\cs{alpha} etc) as well as the following: + +\begin{definition}[\DescribeMacro\glsxtrMathItalicPartial] +\cs{glsxtrMathItalicPartial} +\end{definition} +The partial derivative symbol ($\partial$). + +\begin{definition}[\DescribeMacro\glsxtrMathItalicNabla] +\cs{glsxtrMathItalicNabla} +\end{definition} +The nabla symbol ($\nabla$). + + +\section{Supplementary Commands} + +These commands are provided by \styfmt{glossaries-extra} +for use with \gls{bib2gls}. + +The information provided with \cs{GlsXtrLoadResources} +is written to the \texttt{.aux} file using +\begin{alltt} +\cs{protected@write}\cs{@auxout}\{\cs{glsxtrresourceinit}\}\marg{information} +\end{alltt} +where \meta{information} is the information to pass to +\gls{bib2gls}. The command in the second argument +\begin{definition}[\DescribeMacro\glsxtrresourceinit] +\cs{glsxtrresourceinit} +\end{definition} +may be used to temporarily redefine commands before the +information is written to the file. This does nothing +by default, but may be redefined to allow the use of +short commands for convenience. For example, with: +\begin{verbatim} +\renewcommand{\glsxtrresourceinit}{\let\u\glshex} +\end{verbatim} +you can just use, for example, \verb|\u E6| instead of +\verb|\string\uE6| in the custom rule. This redefinition of \cs{u} +is scoped so its original definition is restored after the write operation. + +If you have multiple resource commands and you want a default set of +options you can supply them in the definition of: +\begin{definition}[\DescribeMacro\GlsXtrDefaultResourceOptions] +\cs{GlsXtrDefaultResourceOptions} +\end{definition} +For example: +\begin{verbatim} +\renewcommand{\GlsXtrDefaultResourceOptions}{selection=all} +\end{verbatim} +This should be done before the resource commands. + +It's possible to specify label prefixes. For example, modifying +the earlier example: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,style=indexgroup]{glossaries-extra} + +\setabbreviationstyle{long-short-desc} + +\GlsXtrLoadResources + [src={abbrvs},sort={letter-nocase},type=main, + label-prefix={abr.}, + group={Abbreviations}] + +\GlsXtrLoadResources + [src={symbols},sort={use},type=main, + label-prefix={sym.}, + group={Symbols}] + +\GlsXtrLoadResources[src={terms},sort={en-GB},type=main + label-prefix={trm.}] + +\begin{document} +\gls{trm.bird} + +\gls{abr.shtml} + +\gls{sym.M} + +\printunsrtglossaries +\end{document} +\end{verbatim} +If you do something like this, you may find it more convenient +to define custom commands that set the prefix. For example: +\begin{verbatim} +\newcommand*{\sym}[2][]{\gls[#1]{sym.#2}} +\end{verbatim} +The problem with this is that the custom command \cs{sym} +doesn't allow for modifiers (such as \cs{gls*} or \cs{gls+}). +Instead you can use: +\begin{definition}[\DescribeMacro\glsxtrnewgls] +\cs{glsxtrnewgls}\oarg{default options}\marg{prefix}\marg{cs} +\end{definition} +which defines the command \meta{cs} that behaves like +\begin{alltt} +\cs{gls}\meta{modifier}[\meta{default options},\meta{options}]\{\meta{prefix}\meta{label}\}\oarg{insert} +\end{alltt} +For example: +\begin{verbatim} +\glsxtrnewgls{sym.}{\sym} +\end{verbatim} +or (to default to no hyperlinks) +\begin{verbatim} +\glsxtrnewgls[hyper=false]{sym.}{\sym} +\end{verbatim} +now you can use \verb|\sym+{M}| to behave like \verb|\gls+{sym.M}|. + +If you also want the plural and first letter upper case +versions you can use +\begin{definition}[\DescribeMacro\glsxtrnewglslike] +\cs{glsxtrnewglslike}\oarg{default +options}\marg{prefix}\marg{\cs{gls}-like cs}\marg{\cs{glspl}-like cs}\marg{\cs{Gls}-like cs}\marg{\cs{Glspl}-like cs} +\end{definition} +For example: +\begin{verbatim} +\glsxtrnewglslike[hyper=false]{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl} +\end{verbatim} +For the all caps versions: +\begin{definition}[\DescribeMacro\glsxtrnewGLSlike] +\cs{glsxtrnewGLSlike}\oarg{default +options}\marg{prefix}\marg{\cs{GLS}-like cs}\marg{\cs{GLSpl}-like cs} +\end{definition} +For example: +\begin{verbatim} +\glsxtrnewGLSlike[hyper=false]{idx.}{\IDX}{\IDXpl} +\end{verbatim} + +There's an analogous command for \cs{rgls}: +\begin{definition}[\DescribeMacro\glsxtrnewrgls] +\cs{glsxtrnewrgls}\oarg{default options}\marg{prefix}\marg{cs} +\end{definition} +and for \cs{rgls}, \cs{rglspl}, \cs{rGls} +and \cs{rGlspl}: +\begin{definition}[\DescribeMacro\glsxtrnewrglslike] +\cs{glsxtrnewrglslike}\oarg{default +options}\marg{prefix}\marg{\cs{rgls}-like cs}\marg{\cs{rglspl}-like +cs}\marg{\cs{rGls}-like cs}\marg{\cs{rGlspl}-like cs} +\end{definition} +and for the all caps: +\begin{definition}[\DescribeMacro\glsxtrnewrGLSlike] +\cs{glsxtrnewrGLSlike}\oarg{default +options}\marg{prefix}\marg{\cs{rGLS}-like cs}\marg{\cs{rGLSpl}-like cs} +\end{definition} + +If you provide your own custom command with just +\cs{newcommand} that has syntax that starts with +\oarg{options}\marg{label}, then you can notify \gls{bib2gls} using: +\begin{definition}[\DescribeMacro\glsxtridentifyglslike] +\cs{glsxtridentifyglslike}\marg{prefix}\marg{command} +\end{definition} +This writes information to the \texttt{.aux} file so that +\gls{bib2gls} can search for the given command when looking +for dependencies. + +Another possibility is to set up known label prefixes, with each +one identified by: +\begin{definition}[\DescribeMacro\glsxtraddlabelprefix] +\cs{glsxtraddlabelprefix}\marg{prefix} +\end{definition} +These should be listed in order of precedence. Since no entries +are defined on the first \LaTeX\ run, the final prefix should +be the fallback. You can prepend a prefix to the list using: +\begin{definition}[\DescribeMacro\glsxtrprependlabelprefix] +\cs{glsxtrprependlabelprefix}\marg{prefix} +\end{definition} +which gives it the highest order of precedence. + +The \meta{prefix} argument may be empty. You can clear the list +with: +\begin{definition}[\DescribeMacro\glsxtrclearlabelprefixes] +\cs{glsxtrclearlabelprefixes} +\end{definition} + +You can test if a prefix is already in the list with: +\begin{definition}[\DescribeMacro\glsxtrifinlabelprefixlist] +\cs{glsxtrifinlabelprefixlist}\marg{prefix}\marg{true}\marg{false} +\end{definition} +In general it's best to avoid adding multiple instances of the same +prefix, so you can check with this command before adding a prefix to +the list. However, it can be useful to repeat a prefix at +the end of the list so that it can be used as a fallback for entries +that haven't yet been defined. + +With the list of possible prefixes set up (including an empty +prefix if necessary), you can use: +\begin{definition}[\DescribeMacro\dgls] +\cs{dgls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +which behaves like +\begin{alltt} +\cs{gls}\oarg{options}\{\meta{prefix}\meta{label}\}\oarg{insert} +\end{alltt} +where \meta{prefix} is the first prefix in the list such that +\meta{prefix}\meta{label} matches a defined entry (or the last entry +in the prefix list if none match). + +There are also analogous commands for the plural and case-changing +versions: +\begin{definition}[\DescribeMacro\dglspl] +\cs{dglspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(uses \cs{glspl}), +\begin{definition}[\DescribeMacro\dGls] +\cs{dGls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(uses \cs{Gls}), +\begin{definition}[\DescribeMacro\dGlspl] +\cs{dGlspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(uses \cs{Glspl}), +\begin{definition}[\DescribeMacro\dGLS] +\cs{dGLS}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(uses \cs{GLS}), +\begin{definition}[\DescribeMacro\dGLSpl] +\cs{dGLSpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(uses \cs{GLSpl}), +\begin{definition}[\DescribeMacro\dglslink] +\cs{dglslink}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(uses \cs{glslink}), +\begin{definition}[\DescribeMacro\dglsdisp] +\cs{dglsdisp}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(uses \cs{glsdisp}). + +These commands are essentially provided for a mixture of single and +dual entries. Suppose the file \texttt{entries.bib} contains: +\begin{verbatim} +@index{duck} +@dualindexabbreviation{svm, + short={SVM}, + long={support vector machine} +} +@dualindexsymbol{pi, + symbol={\ensuremath{\pi}}, + description={ratio of a circle's circumference to its + diameter} +} +\end{verbatim} +and suppose the document code is: +\begin{verbatim} +\documentclass{article} +\usepackage{hyperref} +\usepackage[record,abbreviations,symbols]{glossaries-extra} + +\newcommand{\bibglsnewdualindexsymbolsecondary}[5]{% + \longnewglossaryentry*{#1}{name={#3},category={symbol}, + type={symbols},symbol={#4},#2}{#5}% +} + +\GlsXtrLoadResources[src=entries] + +\begin{document} +First use: \gls{duck}, \gls{svm}, \gls{pi}. +Next use: \gls{duck}, \gls{svm}, \gls{pi}. +\printunsrtglossaries +\end{document} +\end{verbatim} +This uses the default empty primary prefix and \texttt{dual.}\ for +the dual prefix, so \verb|\gls{svm}| is referencing the primary +entry, which is (essentially) an \texttt{@index} type not an +abbreviation. It therefore doesn't follow the abbreviation style, and +it also hyperlinks to the index not to the list of abbreviations. +Similarly for \verb|\gls{pi}|, which references the primary +\texttt{@index} entry rather than the symbol. + +What's really needed is: +\begin{verbatim} +\gls{duck}, \gls{dual.svm}, \gls{dual.pi}. +\end{verbatim} +or with +\begin{verbatim} +\GlsXtrLoadResources[src=entries, + label-prefix={idx.}, + dual-prefix={} +] +\end{verbatim} +then only the entries without a dual need a prefix: +\begin{verbatim} +\gls{idx.duck}, \gls{svm}, \gls{pi}. +\end{verbatim} +Using \cs{glsxtrnewglslike}, as earlier, this can be simplified to: +\begin{verbatim} +\idx{duck}, \gls{svm}, \gls{pi}. +\end{verbatim} +but this requires remembering which terms have duals. + +An alternative is to use \cs{dgls} instead: +\begin{verbatim} +\documentclass{article} +\usepackage{hyperref} +\usepackage[record,abbreviations,symbols]{glossaries-extra} + +\newcommand{\bibglsnewdualindexsymbolsecondary}[5]{% + \longnewglossaryentry*{#1}{name={#3},category={symbol}, + type={symbols},symbol={#4},#2}{#5}% +} + +\GlsXtrLoadResources[src=entries] + +\glsxtraddlabelprefix{dual.} +\glsxtraddlabelprefix{} + +\begin{document} +First use: \dgls{duck}, \dgls{svm}, \dgls{pi}. +Next use: \dgls{duck}, \dgls{svm}, \dgls{pi}. +\printunsrtglossaries +\end{document} +\end{verbatim} +On the first \LaTeX\ call (when the \texttt{.glstex} file doesn't exist), +neither \texttt{dual.svm} nor \texttt{svm} exists, so \cs{dgls} +uses the last prefix (which is empty in this case). This means +that on the first \LaTeX\ run, \verb|\dgls{svm}| behaves like +\verb|\gls{svm}|, which adds a record for the primary +\texttt{svm} entry. The default primary-dual dependency means +that this will cause both the primary (\texttt{svm}) and dual +(\texttt{dual.svm}) entry to be selected. The location will be +added to the primary entry's location list, unless overridden +by resource options, such as \texttt{combine-dual-locations}. + +Once \gls{bib2gls} has been run and the \texttt{.glstex} file +exists, then \texttt{dual.svm} exists. So \verb|\dgls{svm}| will +again first try \texttt{dual.svm} (as \texttt{dual.} is the +first in the list of label prefixes). That now exists, so +\verb|\dgls{svm}| now behaves like \verb|\gls{dual.svm}|, which +follows the abbreviation style and hyperlinks to the list +of abbreviations. + +Similarly for the index-symbol combination \texttt{dual.pi} and +\texttt{pi}. In the case of \verb|\dgls{duck}|, the label +\texttt{dual.duck} never exists, so that's never selected. +The empty prefix is the only one that matches, so +\verb|\dgls{duck}| always behaves like \verb|\gls{duck}|. + +If you haven't used \texttt{combine-dual-locations} an extra +\gls{bib2gls}+\LaTeX\ run may be required to correct the location +lists. + +If you change the label prefixes, remember to update the +corresponding \cs{glsxtraddlabelprefix}\marg{prefix}. +If no prefixes have been added to the list (or if the list is +cleared), just an empty prefix is assumed. + +As from version 1.8, \gls{bib2gls} provides hooks that identify +the label prefixes in the \texttt{.glstex} file: +\begin{alltt} +\ics{bibglstertiaryprefixlabel}\marg{prefix} +\ics{bibglsdualprefixlabel}\marg{prefix} +\ics{bibglsprimaryprefixlabel}\marg{prefix} +\end{alltt} +These do nothing by default, but they can be defined before +the resource file is loaded to set up the prefix list. For +example: +\begin{verbatim} +\newcommand{\bibglsprimaryprefixlabel}[1]{\glsxtraddlabelprefix{#1}} +\newcommand{\bibglsdualprefixlabel}[1]{\glsxtrprependlabelprefix{#1}} +\GlsXtrLoadResources[src=entries] +\end{verbatim} +Remember that this will only have an effect once the +\texttt{.glstex} file has been created. The prefix list will be empty +on the first run (which is treated as a single empty prefix). +If this isn't a suitable fallback, it may be necessary to add one +after all the resource commands: +\begin{verbatim} +\newcommand{\bibglsprimaryprefixlabel}[1]{\glsxtraddlabelprefix{#1}} +\newcommand{\bibglsdualprefixlabel}[1]{\glsxtrprependlabelprefix{#1}} +\GlsXtrLoadResources[src=entries,label-prefix={idx.}] +\glsxtraddlabelprefix{idx.} +\end{verbatim} +Although this rather defeats the purpose of using the hooks as you +still have to keep track of the fallback prefix. + +\section{Record Counting} +\label{sec:recordcount} + +As from version 1.1 of \gls{bib2gls}, you can save the total +record count for each entry by invoking \gls{bib2gls} +with the \texttt{-{}-record-count} or \texttt{-{}-record-count-unit} +switches. These options will ensure that when each entry +is written to the \texttt{.glstex} file \gls{bib2gls} will +additionally set the following internal fields for that entry: +\begin{itemize} +\item \texttt{recordcount}: set to the total +number of records found for the entry; +\item \texttt{recordcount.\meta{counter}}: set to the total +number of records found for the entry for the given counter. +\end{itemize} +If \texttt{-{}-record-count-unit} is used then additionally: +\begin{itemize} +\item \texttt{recordcount.\meta{counter}.\meta{location}}: set to the total +number of records found for the entry for the given counter with the +given location. +\end{itemize} +Only use the unit counting option if the locations don't contain any special +characters. If you really need it with locations that may contain +formatting commands, then you can try redefining: +\begin{definition}[\DescribeMacro\glsxtrdetoklocation] +\cs{glsxtrdetoklocation}\marg{location} +\end{definition} +so that it detokenizes \meta{location} but take care when +using \cs{GlsXtrLocationRecordCount} with commands like +\cs{thepage} as they can end up becoming detokenized +too early. + +Note that the record count includes locations that \gls{bib2gls} +discards, such as ignored records, duplicates and partial +duplicates. It doesn't include cross-reference records. For +example, if \verb|\gls{bird}| is used twice on page~1, once on +page~2 and fours times on page~3, and +\verb|\gls[counter=section]{bird}| is used once in section~3, then +the total record count (stored in the \texttt{recordcount} field) is +$2+1+4+1=8$, the total for the \texttt{page} counter (stored in the +\texttt{recordcount.page} field) is $2+1+4=7$, and the total for the +\texttt{section} counter (stored in the \texttt{recordcount.section} +field) is 1. + +With the unit counting on as well, the field +\texttt{recordcount.page.1} is set to 2, \texttt{recordcount.page.2} +is set to 1, \texttt{recordcount.page.3} is set to 4 and +\texttt{recordcount.section.3} is set to 1. + +You can access these fields using the following commands which +will expand to the field value if set or to 0 if unset: +\begin{definition}[\DescribeMacro\GlsXtrTotalRecordCount] +\cs{GlsXtrTotalRecordCount}\marg{label} +\end{definition} +This expands to the total record count for the entry given by +\meta{label}. +\begin{verbatim} +\GlsXtrTotalRecordCount{bird} +\end{verbatim} +expands to 8. + +\begin{definition}[\DescribeMacro\GlsXtrRecordCount] +\cs{GlsXtrRecordCount}\marg{label}\marg{counter} +\end{definition} +This expands to the counter total for the entry given by +\meta{label} where \meta{counter} is the counter name. +For example: +\begin{verbatim} +\GlsXtrRecordCount{bird}{page} +\end{verbatim} +expands to 7 and +\begin{verbatim} +\GlsXtrRecordCount{bird}{section} +\end{verbatim} +expands to 1. + +\begin{definition}[\DescribeMacro\GlsXtrLocationRecordCount] +\cs{GlsXtrLocationRecordCount}\marg{label}\marg{counter}\marg{location} +\end{definition} +This expands to the total for the given location. For example +\begin{verbatim} +\GlsXtrLocationRecordCount{bird}{page}{3} +\end{verbatim} +expands to 4. Be careful about using \cs{thepage} in the +\meta{location} part. Remember that due to \TeX's asynchronous +output routine, \cs{thepage} may not be correct. + +There are commands analogous to the entry counting commands like +\cs{cgls} and \cs{cglsformat} that are triggered by the record count. +These are listed below. + +\begin{definition}[\DescribeMacro\rgls] +\cs{rgls}\meta{modifier}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rglspl] +\cs{rglspl}\meta{modifier}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rGls] +\cs{rGls}\meta{modifier}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rGlspl] +\cs{rGlspl}\meta{modifier}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rGLS] +\cs{rGLS}\meta{modifier}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rGLSpl] +\cs{rGLSpl}\meta{modifier}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +These commands check the \catattr{recordcount} attribute +which, if set, should be a number. For example: +\begin{verbatim} +\glssetcategoryattribute{abbreviation}{recordcount}{1} +\end{verbatim} +For convenience, you can use +\begin{definition}[\DescribeMacro\GlsXtrSetRecordCountAttribute] +\cs{GlsXtrSetRecordCountAttribute}\marg{category list}\marg{n} +\end{definition} +to set the \catattr{recordcount} attribute to \meta{n} +for all the categories listed in \meta{category list}. + +The \cs{rgls}-like commands use +\begin{definition}[\DescribeMacro\glsxtrifrecordtrigger] +\cs{glsxtrifrecordtrigger}\marg{label}\marg{trigger +code}\marg{normal} +\end{definition} +to determine whether the \cs{rgls}-like command should behave like +its \cs{gls} counterpart (\meta{normal}) or whether it should +instead use \meta{trigger code}. + +This command checks if the \catattr{recordcount} attribute is set. +If not is just does \meta{normal}, otherwise it tests +if +\begin{definition}[\DescribeMacro\glsxtrrecordtriggervalue] +\cs{glsxtrrecordtriggervalue}\marg{label} +\end{definition} +is greater than the value given in the \catattr{recordcount} +attribute for that entry's category. If true, this does +\meta{normal} otherwise it does \meta{trigger code}. +The default definition of the trigger value command is: +\begin{verbatim} +\newcommand*{\glsxtrrecordtriggervalue}[1]{% + \GlsXtrTotalRecordCount{#1}% +} +\end{verbatim} +The \meta{trigger code} part writes a record with +the \gloskey[glslink]{format} set to \texttt{glstriggerrecordformat} (which +\gls{bib2gls} v1.1+ recognises as a special type of ignored location +format) and does \meta{trigger format}. Then it +unsets the \gls{firstuseflag}. Note that it doesn't +implement the post-link hook. This ensures that the record +count is correct on the next run. + +The \meta{trigger format} depends on the \cs{rgls}-like +command used and will be one of the following: +\begin{definition}[\DescribeMacro\rglsformat] +\cs{rglsformat}\marg{label}\marg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rglsplformat] +\cs{rglsplformat}\marg{label}\marg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rGlsformat] +\cs{rGlsformat}\marg{label}\marg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rGlsplformat] +\cs{rGlsplformat}\marg{label}\marg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rGLSformat] +\cs{rGLSformat}\marg{label}\marg{insert} +\end{definition} +\begin{definition}[\DescribeMacro\rGLSplformat] +\cs{rGLSplformat}\marg{label}\marg{insert} +\end{definition} +These all behave much like their \cs{cglsformat} counterparts. If +the entry's \catattr{regular} attribute is set or if the entry +doesn't have a long form, the first or first plural is used, +otherwise the long or long plural form is used. + +You can use +\begin{definition}[\DescribeMacro\glsxtrenablerecordcount] +\cs{glsxtrenablerecordcount} +\end{definition} +to redefine \cs{gls}, \cs{glspl}, \cs{Gls}, \cs{Glspl}, +\cs{GLS}, \cs{GLSpl} to \cs{rgls}, \cs{rglspl}, \cs{rGls}, \cs{rGlspl}, +\cs{rGLS}, \cs{rGLSpl}, respectively, for convenience. + +If you don't want the entries that use \meta{trigger code} +to appear in the glossary, you need to use the resource option +\texttt{trigger-type} to assign them to another glossary. +For example: +\begin{verbatim} +\documentclass{article} + +\usepackage[record]{glossaries-extra} + +\newignoredglossary{ignored} + +\GlsXtrLoadResources[ + src=example-glossaries-acronym, + trigger-type=ignored, + category=abbreviation +] + +\glsxtrenablerecordcount +\GlsXtrSetRecordCountAttribute{abbreviation}{1} + +\begin{document} +\gls{lid}. \gls{stc}. \gls{lid}. \gls{aeu}. +\gls{upa}. \gls{aeu}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +In the above, \texttt{stc} and \texttt{upa} both only have +one record, so they are assigned to the \texttt{ignored} +glossary instead of the \texttt{main} one. + +\chapter{Miscellaneous New Commands} +\label{sec:miscnew} + +The \styfmt{glossaries} package provides \ics{glsrefentry} entry to +cross-reference entries when used with the \pkgopt{entrycounter} or +\pkgopt{subentrycounter} options. The \styfmt{glossaries-extra} +package provides a supplementary command +\begin{definition}[\DescribeMacro\glsxtrpageref] +\cs{glsxtrpageref}\marg{label} +\end{definition} +that works in the same way except that it uses \ics{pageref} +instead of \ics{ref}. + +You can copy an entry to another glossary using +\begin{definition}[\DescribeMacro\glsxtrcopytoglossary] +\cs{glsxtrcopytoglossary}\marg{entry-label}\marg{glossary-type} +\end{definition} +This appends \meta{entry-label} to the end of the internal +list for the glossary given by \meta{glossary-type}. +Be careful if you use the \sty{hyperref} package as this +may cause duplicate hypertargets. You will need to change +\cs{glolinkprefix} to another value or disable hyperlinks +when you display the duplicate. Alternatively, use the new +\gloskey[printglossary]{target} key to switch off the targets: +\begin{verbatim} +\printunsrtglossary[target=false] +\end{verbatim} + +The \styfmt{glossaries} package allows you to set preamble code +for a given glossary type using \cs{setglossarypreamble}. This +overrides any previous setting. With \styfmt{glossaries-extra} +(as from v1.12) you can instead append to the preamble +using +\begin{definition}[\DescribeMacro\apptoglossarypreamble] +\cs{apptoglossarypreamble}\oarg{type}\marg{code} +\end{definition} +or prepend using +\begin{definition}[\DescribeMacro\pretoglossarypreamble] +\cs{pretoglossarypreamble}\oarg{type}\marg{code} +\end{definition} + +\section{Entry Fields} +\label{sec:fields} + +A field may now be used to store the name of a text-block command +that takes a single argument. The field is given by +\begin{definition}[\DescribeMacro\GlsXtrFmtField] +\cs{GlsXtrFmtField} +\end{definition} +The default value is \texttt{\GlsXtrFmtField}. Note that the +value must be the control sequence name \emph{without the initial +backslash}. + +For example: +\begin{verbatim} +\newcommand*{\mtx}[1]{\boldsymbol{#1}} +\newcommand*{\mtxinv}[1]{\mtx{#1}\sp{-1}} + +\newglossaryentry{matrix}{% + name={matrix}, + symbol={\ensuremath{\mtx{M}}}, + plural={matrices}, + user1={mtx}, + description={rectangular array of values} +} + +\newglossaryentry{identitymatrix}{% + name={identity matrix}, + symbol={\ensuremath{\mtx{I}}}, + plural={identity matrices}, + description={a diagonal matrix with all diagonal elements equal to +1 and all other elements equal to 0} +} + +\newglossaryentry{matrixinv}{% + name={matrix inverse}, + symbol={\ensuremath{\mtxinv{M}}}, + user1={mtxinv}, + description={a square \gls{matrix} such that + $\mtx{M}\mtxinv{M}=\glssymbol{identitymatrix}$} +} +\end{verbatim} + +There are two commands provided that allow you to apply the +command to an argument: +\begin{definition}[\DescribeMacro\glsxtrfmt] +\cs{glsxtrfmt}\oarg{options}\marg{label}\marg{text} +\end{definition} +This effectively does +\begin{alltt} +\cs{glslink}[\meta{default-options},\meta{options}]\marg{label}\{\cs{glsxtrfmtdisplay}\marg{cs name}\marg{text}\{\}\} +\end{alltt} +where \meta{cs name} is the control +sequence name supplied in the provided field, which must be defined +to take a single required argument. Although it effectively +acts like \cs{glslink} it misses out the post-link hook. + +The default \meta{default-options} are given by +\begin{definition}[\DescribeMacro\GlsXtrFmtDefaultOptions] +\cs{GlsXtrFmtDefaultOptions} +\end{definition} +This is defined as \texttt{\GlsXtrFmtDefaultOptions} but may +be redefined as appropriate. Note that the replacement text of +\cs{GlsXtrFmtDefaultOptions} is prepended to the optional +argument of \cs{glslink}. + +As from version 1.23, there's also a starred version of +this command that has a final optional argument: +\begin{definition}[\DescribeMacro{\glsxtrfmt*}] +\cs{glsxtrfmt*}\oarg{options}\marg{label}\marg{text}\oarg{insert} +\end{definition} +Both the starred and unstarred versions use: +\begin{definition}[\DescribeMacro\glsxtrfmtdisplay] +\cs{glsxtrfmtdisplay}\marg{cs name}\marg{text}\marg{insert} +\end{definition} +within the link text. +In the case of the unstarred version \meta{insert} will be empty. +It will also be empty if the final option argument is +missing from the starred form. If the entry given by \meta{label} +is undefined \cs{glsxtrfmt} and \cs{glsxtrfmt*} will issue +an error (or warning if \pkgopt[warn]{undefaction}). +There won't be a warning or error if the entry is defined by +the given field is missing. In either case, +(the entry is undefined or the field is missing) \meta{cs name} +will be \texttt{@firstofone} otherwise it will be the +field value. The default definition is: +\begin{verbatim} +\newcommand{\glsxtrfmtdisplay}[3]{\csuse{#1}{#2}#3} +\end{verbatim} +which puts \meta{text} inside the argument of the control sequence +and \meta{insert} outside it (but it will still be inside the +link text). + +\begin{important} +Remember that nested links cause a problem so avoid using +commands like \cs{gls} or \cs{glsxtrfmt} within \meta{text}. +\end{important} + +For example: +\begin{verbatim} +\[ + \glsxtrfmt{matrix}{A} + \glsxtrfmt{matrixinv}{A} + = + \glssymbol{identitymatrix} +\] +\end{verbatim} +If the default options are set to \texttt{noindex} then +\cs{glsxtrfmt} won't index, but will create a hyperlink (if +\sty{hyperref} has been loaded). This can be changed so that +it also suppresses the hyperlink: +\begin{verbatim} +\renewcommand{\GlsXtrFmtDefaultOptions}{hyper=false,noindex} +\end{verbatim} + +Note that \cs{glsxtrfmt} won't work with PDF bookmarks. Instead +you can use +\begin{definition}[\DescribeMacro\glsxtrentryfmt] +\cs{glsxtrentryfmt}\marg{label}\marg{text} +\end{definition} +This uses \cs{texorpdfstring} and will simply expand to \meta{text} +within the PDF bookmarks, but in the document it will do +\meta{cs}\marg{text} if a control sequence name has been provided +or just \meta{text} otherwise. + +The \styfmt{glossaries} package provides \cs{glsaddstoragekey} to +add new keys. This command will cause an error if the key has +already been defined. The \styfmt{glossaries-extra} package provides +a supplementary command that will only define the key if it doesn't +already exist: +\begin{definition}[\DescribeMacro\glsxtrprovidestoragekey] +\cs{glsxtrprovidestoragekey}\marg{key}\marg{default}\marg{cs} +\end{definition} +If the key has already been defined, it will still provide the command given in +the third argument \meta{cs} (if it hasn't already been defined). Unlike +\cs{glsaddstoragekey}, \meta{cs} may be left empty if you're happy +to just use \cs{glsfieldfetch} to fetch the value of this new key. + +You can test if a key has been provided with: +\begin{definition}[\DescribeMacro\glsxtrifkeydefined] +\cs{glsxtrifkeydefined}\marg{key}\marg{true}\marg{false} +\end{definition} +This tests if \meta{key} is available for use in the +\meta{key}=\value{value} list in the second argument of +\cs{newglossaryentry} (or the optional argument of +commands like \cs{newabbreviation}). The corresponding +field may not have been set for any of the entries if no +default was provided. + +There are now commands provided to set individual fields. Note that +these only change the specified field, not any related values. For +example, changing the value of the \gloskey{text} field won't update +the \gloskey{plural} field. There are also some fields that +should really only be set when entries are defined (such +as the \gloskey{parent} field). Unexpected results may occur +if they are subsequently changed. + +\begin{definition}[\DescribeMacro\GlsXtrSetField] +\cs{GlsXtrSetField}\marg{label}\marg{field}\marg{value} +\end{definition} +Sets the field given by \meta{field} to \meta{value} for the entry +given by \meta{label}. No expansion is performed. It's not +necessary for the field to have been defined as a key. You +can access the value later with \cs{glsxtrusefield}. Note that +\cs{glsxtrifkeydefined} only tests if a key has been defined for use +with commands like \cs{newglossaryentry}. If a field without a +corresponding key is assigned a value, the key remains undefined. +This command is robust. + +\cs{GlsXtrSetField} uses +\begin{definition}[\DescribeMacro\glsxtrsetfieldifexists] +\cs{glsxtrsetfieldifexists}\marg{label}\marg{field}\marg{code} +\end{definition} +where \meta{label} is the entry label and \meta{code} is the +assignment code. + +This command just uses \ics{glsdoifexists}\marg{label}\marg{code} +(ignoring the \meta{field} argument), so by default it causes an +error if the entry doesn't exist. This can be changed to a warning +with \pkgopt[warn]{undefaction}. You can redefine +\cs{glsxtrsetfieldifexists} to simply do \meta{code} if you want to +skip the existence check. Alternatively you can instead use +\begin{definition}[\DescribeMacro\glsxtrdeffield] +\cs{glsxtrdeffield}\marg{label}\marg{field}\meta{arguments}\marg{replacement text} +\end{definition} +This simply uses \sty{etoolbox}'s \cs{csdef} without any checks. +This command isn't robust. There is also a version that uses +\cs{protected@csedef} instead:\footnote{Pre version 1.28 used +\cs{csedef}.} +\begin{definition}[\DescribeMacro\glsxtredeffield] +\cs{glsxtredeffield}\marg{label}\marg{field}\meta{arguments}\marg{replacement text} +\end{definition} + +\begin{definition}[\DescribeMacro\gGlsXtrSetField] +\cs{gGlsXtrSetField}\marg{label}\marg{field}\marg{value} +\end{definition} +As \cs{GlsXtrSetField} but globally. + +\begin{definition}[\DescribeMacro\eGlsXtrSetField] +\cs{eGlsXtrSetField}\marg{label}\marg{field}\marg{value} +\end{definition} +As \cs{GlsXtrSetField} but uses protected expansion. + +\begin{definition}[\DescribeMacro\xGlsXtrSetField] +\cs{xGlsXtrSetField}\marg{label}\marg{field}\marg{value} +\end{definition} +As \cs{gGlsXtrSetField} but uses protected expansion. + +\begin{definition}[\DescribeMacro\GlsXtrLetField] +\cs{GlsXtrLetField}\marg{label}\marg{field}\marg{cs} +\end{definition} +Sets the field given by \meta{field} to the replacement text of \meta{cs} +for the entry given by \meta{label} (using \cs{let}). + +\begin{definition}[\DescribeMacro\csGlsXtrLetField] +\cs{csGlsXtrLetField}\marg{label}\marg{field}\marg{cs name} +\end{definition} +As \cs{GlsXtrLetField} but the control sequence name is supplied +instead. + +\begin{definition}[\DescribeMacro\GlsXtrLetFieldToField] +\cs{GlsXtrLetFieldToField}\marg{label-1}\marg{field-1}\marg{label-2}\marg{field-2} +\end{definition} +Sets the field given by \meta{field-1} for the entry given by +\meta{label-1} to the field given by \meta{field-2} for the entry +given by \meta{label-2}. There's no check for the existence of +\meta{label-2}, but +\cs{glsxtrsetfieldifexists}\marg{label-1}\marg{field-1}\marg{code} +is still used, as for \cs{GlsXtrSetField}. + +The \styfmt{glossaries} package provides \ics{ifglshasfield} +to determine if a field has been set. The \styfmt{glossaries-extra} +package provides a simpler version: +\begin{definition}[\DescribeMacro\glsxtrifhasfield] +\cs{glsxtrifhasfield}\marg{field}\marg{label}\marg{true}\marg{false} +\end{definition} +(New to v1.19.) Note that in this case the \meta{field} must be the +\emph{internal} field label (for example, \texttt{useri} rather than +\texttt{user1}). +Unlike \cs{ifglshasfield}, this version doesn't complain if the +entry (given by \meta{label}) or the field don't exist and +will simply do \meta{false}. If the field does exist for the given +entry and it's not empty, the \meta{true} part is done otherwise it +does \meta{false}. Within \meta{true} you may use +\begin{definition}[\DescribeMacro\glscurrentfieldvalue] +\cs{glscurrentfieldvalue} +\end{definition} +to access the field value. This command includes grouping +which scopes the \meta{true} and \meta{false} parts. +The starred version +\begin{definition}[\DescribeMacro{\glsxtrifhasfield*}] +\cs{glsxtrifhasfield*}\marg{field}\marg{label}\marg{true}\marg{false} +\end{definition} +omits the implicit grouping. + +\begin{important} +Be careful of keys that use \cs{relax} as the default value +(such as the \gloskey{symbol}). Use \cs{ifglshassymbol} instead. +\end{important} + +There is also a version that simply uses \cs{ifcsundef}. It +doesn't save the field value, but can be used if you only +need to check if the field is defined without accessing it: +\begin{definition}[\DescribeMacro\GlsXtrIfFieldUndef] +\cs{GlsXtrIfFieldUndef}\marg{field}\marg{label}\marg{true}\marg{false} +\end{definition} + +\begin{important} +There's a difference between an undefined field and an unset field. +An undefined field hasn't been assigned any value (no +associated internal control sequence has been defined). If a defined +field has been defined to empty, then it's considered unset. +\cs{GlsXtrIfFieldUndef} implement \meta{false} for a defined +but empty field whereas \cs{glsxtrifhasfield} and \cs{ifglshasfield} +will implement \meta{false} a defined but empty field. +Remember that any keys that may be used in \cs{newglossaryentry} +will have a default value if not provided. In many cases, the +default value is empty, so only use \cs{GlsXtrIfFieldUndef} +for fields that can only be defined through commands like +\cs{GlsXtrSetField}. +\end{important} + +You can test if a field value equals a string using +\begin{definition}[\DescribeMacro{\GlsXtrIfFieldEqStr}] +\cs{GlsXtrIfFieldEqStr}\marg{field}\marg{label}\marg{text}\marg{true}\marg{false} +\end{definition} +If the entry exists and has the given field set to the +given text then this does \meta{true} otherwise it does +\meta{false}. This uses \cs{glsxtrifhasfield} +to test if the field exists and then compares the replacement +text of \cs{glscurrentfieldvalue} with \meta{text} using +\sty{etoolbox}'s \cs{ifdefstring}. Version 1.39 introduced +a starred form of this command, which uses the starred form +of \cs{glsxtrifhasfield}. + +As from version 1.31, there's a similar command: +\begin{definition}[\DescribeMacro{\GlsXtrIfFieldEqXpStr}] +\cs{GlsXtrIfFieldEqXpStr}\marg{field}\marg{label}\marg{text}\marg{true}\marg{false} +\end{definition} +This is like \cs{GlsXtrIfFieldEqStr} but first (protected) fully +expands \meta{text} (but not the field value). If you want to +compare the (protected) full expansion of both the field value and \meta{text} +use: +\begin{definition}[\DescribeMacro{\GlsXtrIfXpFieldEqXpStr}] +\cs{GlsXtrIfXpFieldEqXpStr}\marg{field}\marg{label}\marg{text}\marg{true}\marg{false} +\end{definition} +Again, version 1.39 introduced a starred form of these commands, +which use the starred form of \cs{glsxtrifhasfield}. + +As from v1.31, if a field represents a numeric (integer) value, you +can use the following two numeric tests. If the field is set, it must +expand to an integer. You may use \cs{glscurrentfieldvalue} +within \meta{true} or \meta{false} to access the actual value. Both \meta{true} +and \meta{false} are scoped. If the field is undefined or empty, +the value is assumed to be 0, and \cs{glscurrentfieldvalue} is set +accordingly. As from version 1.39, these numeric tests have +starred versions. The unstarred versions add implicit grouping. +The starred versions don't. + +To test if the value is non-zero: +\begin{definition}[\DescribeMacro{\GlsXtrIfFieldNonZero}] +\cs{GlsXtrIfFieldNonZero}\marg{field}\marg{label}\marg{true}\marg{false} +\end{definition} +Alternatively, you can test if the field expands to a specific +number using: +\begin{definition}[\DescribeMacro{\GlsXtrIfFieldEqNum}] +\cs{GlsXtrIfFieldEqNum}\marg{field}\marg{label}\marg{n}\marg{true}\marg{false} +\end{definition} +This does \meta{true} if the field value equals \meta{n} +(using \cs{ifnum} for the comparison) otherwise it does +\meta{false}. For a more general numeric comparison you +can use: +\begin{definition}[\DescribeMacro{\GlsXtrIfFieldCmpNum}] +\cs{GlsXtrIfFieldCmpNum}\marg{field}\marg{label}\marg{comparison}\marg{n}\marg{true}\marg{false} +\end{definition} +where \meta{comparison} is one of \texttt{=}, \texttt{<} or +\texttt{>}. + +The \styfmt{glossaries} package provides \ics{glsfieldfetch} which +can be used to fetch the value of the given field and store it in a +control sequence. The \styfmt{glossaries-extra} package provides +another way of accessing the field value: +\begin{definition}[\DescribeMacro\glsxtrusefield] +\cs{glsxtrusefield}\marg{entry-label}\marg{field-label} +\end{definition} +This works in the same way as commands like \cs{glsentrytext} but +the field label is specified in the first argument. Note that the +\meta{field-label} corresponds to the internal field tag, which +isn't always the same as the key name. See Table~4.1 of the +\sty{glossaries} manual. No error occurs if the entry or field +haven't been defined. This command is not robust. + +There is also a version that converts the first letter to uppercase +(analogous to \cs{Glsentrytext}): +\begin{definition}[\DescribeMacro\Glsxtrusefield] +\cs{Glsxtrusefield}\marg{entry-label}\marg{field-label} +\end{definition} +and, as from v1.37, a command that converts the entire value to upper case: +\begin{definition}[\DescribeMacro\GLSxtrusefield] +\cs{GLSxtrusefield}\marg{entry-label}\marg{field-label} +\end{definition} + +If you want to use a field to store a list that can be used +as an \sty{etoolbox} internal list, you can use the following +command that adds an item to the field using \sty{etoolbox}'s +\cs{listcsadd}: +\begin{definition}[\DescribeMacro\glsxtrfieldlistadd] +\cs{glsxtrfieldlistadd}\marg{label}\marg{field}\marg{item} +\end{definition} +where \meta{label} is the entry's label, \meta{field} is +the entry's field and \meta{item} is the item to add. There +are analogous commands that use \cs{listgadd}, \cs{listeadd} +and \cs{listxadd}: +\begin{definition}[\DescribeMacro\glsxtrfieldlistgadd] +\cs{glsxtrfieldlistgadd}\marg{label}\marg{field}\marg{item} +\end{definition} +\begin{definition}[\DescribeMacro\glsxtrfieldlisteadd] +\cs{glsxtrfieldlisteadd}\marg{label}\marg{field}\marg{item} +\end{definition} +\begin{definition}[\DescribeMacro\glsxtrfieldlistxadd] +\cs{glsxtrfieldlistxadd}\marg{label}\marg{field}\marg{item} +\end{definition} +You can then iterate over the list using: +\begin{definition}[\DescribeMacro\glsxtrfielddolistloop] +\cs{glsxtrfielddolistloop}\marg{label}\marg{field} +\end{definition} +or +\begin{definition}[\DescribeMacro\glsxtrfieldforlistloop] +\cs{glsxtrfieldforlistloop}\marg{label}\marg{field}\marg{handler} +\end{definition} +that internally use \cs{dolistcsloop} and \cs{forlistloop}, +respectively. + +There are also commands that use \cs{ifinlistcs}: +\begin{definition}[\DescribeMacro\glsxtrfieldifinlist] +\cs{glsxtrfieldifinlist}\marg{label}\marg{field}\marg{item}\marg{true}\marg{false} +\end{definition} +and \cs{xifinlistcs} +\begin{definition}[\DescribeMacro\glsxtrfieldxifinlist] +\cs{glsxtrfieldxifinlist}\marg{label}\marg{field}\marg{item}\marg{true}\marg{false} +\end{definition} + +See the \sty{etoolbox}'s user manual for further +details of these commands, in particular the limitations +of \cs{ifinlist}. + +If the field has a comma-separated list value instead, you +can iterate over it using: +\begin{definition}[\DescribeMacro\glsxtrforcsvfield] +\cs{glsxtrforcsvfield}\marg{label}\marg{field}\marg{handler} +\end{definition} +where again \meta{handler} is a control sequence that takes +a single argument. Unlike the \sty{etoolbox} loops, this +doesn't ignore empty elements nor does it discard leading / trailing +spaces. Internally it uses \cs{@for} (modified by \sty{xfor} +which is automatically loaded by \sty{glossaries}). The +\sty{xfor} package modifies the behaviour of \cs{@for} to allow +the loop to be broken prematurely using \cs{@endfortrue}. +The \cs{glsxtrforcsvfield} command locally defines +a user level command: +\begin{definition}[\DescribeMacro\glsxtrendfor] +\cs{glsxtrendfor} +\end{definition} +which is just a synonym for \cs{@endfortrue}. + +The loop is performed within the true part of \cs{glsxtrifhasfield} +so scoping is automatically applied. + +As from version 1.32, if the field given by +\begin{definition}[\DescribeMacro\GlsXtrForeignTextField] +\cs{GlsXtrForeignTextField} +\end{definition} +(which defaults to \texttt{userii}) contains a locale tag, then +\begin{definition}[\DescribeMacro\GlsXtrForeignText] +\cs{GlsXtrForeignText}\marg{entry label}\marg{text} +\end{definition} +can be used to encapsulate \meta{text} in +\cs{foreignlanguage}\marg{dialect}\marg{text} where \meta{dialect} +is obtained from the locale tag through \sty{tracklang}'s +\ics{GetTrackedDialectFromLanguageTag} command. You need at least +\sty{tracklang} v1.3.6 for this to work properly. The \meta{dialect} +must be one that's tracked (which typically means that \sty{babel} +or \sty{polyglossia} has been loaded with the appropriate setting +for that language). If \cs{foreignlanguage} hasn't been defined, +this just does \meta{text}. +For example: +\begin{verbatim} +\documentclass{article} + +\usepackage[main=british,brazilian,ngerman]{babel} +\usepackage{glossaries-extra} + +\setabbreviationstyle{long-short-user} +\newabbreviation + [user1={Associa\c{c}\~ao Brasileria de Normas T\'ecnicas}, + user2= {pt-BR} + ] + {abnt}{ABNT}{Brazilian National Standards Organization} + +\newabbreviation + [user1={Deutsches Institut f\"ur Normung e.V.}, + user2={de-DE-1996}] + {din}{DIN}{German Institute for Standardization} + +\renewcommand*{\glsxtruserparen}[2]{% + \glsxtrfullsep{#2}% + \glsxtrparen + {#1% + \ifglshasfield{\glsxtruserfield}{#2}% + {, \emph{\GlsXtrForeignText{#2}{\glscurrentfieldvalue}}}% + {}% + }% +} + +\begin{document} +\gls{abnt}, \gls{din}. +\end{document} +\end{verbatim} + + +When using the \pkgopt{record} option, in addition to recording the +usual location, you can also record the current value +of another counter at the same time using the preamble-only command: +\begin{definition}[\DescribeMacro\GlsXtrRecordCounter] +\cs{GlsXtrRecordCounter}\marg{counter name} +\end{definition} +For example: +\begin{verbatim} +\usepackage[record]{glossaries-extra} +\GlsXtrRecordCounter{section} +\end{verbatim} +Each time an entry is referenced with commands like \cs{gls} +or \cs{glstext}, the \texttt{.aux} file will not only contain +the \cs{glsxtr@record} command but also +\begin{alltt} +\cs{glsxtr@counterrecord}\marg{label}\{section\}\marg{n} +\end{alltt} +where \meta{n} is the current expansion of \cs{thesection} +and \meta{label} is the entry's label. On the next run, when the +\texttt{.aux} file is run, this command will do +\begin{alltt} +\cs{glsxtrfieldlistgadd}\marg{label}\{record.\meta{counter}\}\marg{n} +\end{alltt} +In the above example, if \verb|\gls{bird}| is used in section~1.2 +this would be +\begin{verbatim} +\glsxtrfieldlistgadd{bird}{record.section}{1.2} +\end{verbatim} +Note that there's no key corresponding to this new +\texttt{record.section} field, but its value can be +accessed with \cs{glsxtrfielduse} or the list can be +iterated over with \cs{glsxtrfielddolistloop} etc. + +\section{Display All Entries Without Sorting or Indexing} +\label{sec:printunsrt} + +\begin{definition}[\DescribeMacro\printunsrtglossary] +\cs{printunsrtglossary}\oarg{options} +\end{definition} +This behaves like \cs{printnoidxglossary} but never sorts the +entries and always lists all the defined entries for the given +glossary (and doesn't require \cs{makenoidxglossaries}). +If you want to use one of the \env{tabular}-like +styles with \cs{printunsrtglossary}, make sure you load +\sty{glossaries-extra-stylemods} which modifies +the definition of \cs{glsgroupskip} to avoid the +\qt{Incomplete \cs{iftrue}} error that may otherwise occur. + +There's also a starred form +\begin{definition}[\DescribeMacro{\printunsrtglossary*}] +\cs{printunsrtglossary}*\oarg{options}\marg{code} +\end{definition} +which is equivalent to +\begin{alltt} +\cs{begingroup} + \meta{code}\cs{printunsrtglossary}\oarg{options}\% +\cs{endgroup} +\end{alltt} +Note that unlike \cs{glossarypreamble}, the supplied \meta{code} is +done before the glossary header. + +This means you now have the option to simply list all entries on the +first \LaTeX\ run without the need for a post-processor, however +there will be no \gls{numberlist} in this case, as that has to be +set by a post-processor such as \gls{bib2gls} (see +\sectionref{sec:bib2gls}). + +\begin{important} +No attempt is made to gather hierarchical elements. +If child entries aren't defined immediately after their parent +entry, they won't be together in the glossary when using +\cs{printunsrtglossary}. +\end{important} + +There's a difference in behaviour depending on whether or not the +\gloskey{group} key is defined. If not defined (default), the +group label will be formed from the first letter of the +\gloskey{name} field. The corresponding group title will be obtained +as discussed in \sectionref{sec:glosstylemods}. This can lead to an +odd effect if you are using a style that separates letter groups +when the ordering isn't alphabetical. + +If the \gloskey{group} key is defined (which it is with the +\pkgopt{record} option) then the group label will be obtained from +the value of that field. If the field is empty, \emph{no grouping is +performed}, even if the style supports it. (That is, there won't be +a header or a vertical separation.) If the \gloskey{group} field is +non-empty, then the corresponding title is obtained as described +earlier. + +If you want to use a different field, you can redefine +\begin{definition}[\DescribeMacro\glsxtrgroupfield] +\cs{glsxtrgroupfield} +\end{definition} +to the relevant internal field label, but the \gloskey{group} +\emph{key} must still be defined (through the \pkgopt{record} option +or with commands like \cs{glsaddstoragekey}) to ensure that +\cs{printunsrtglossary} uses \cs{glsxtrgroupfield}. (This method is +used by \gls{bib2gls} for secondary entries, which have the group +label stored in the \texttt{secondarygroup} internal field.) + +If you have any entries with the \gloskey{see} key set, you will +need the \sty{glossaries} package option \pkgopt[ignore]{seenoindex} +or \pkgopt[warn]{seenoindex} to prevent an error occurring from the +automated \cs{glssee} normally triggered by this key. The +\pkgopt[only]{record} package option will automatically deal with +this. + +For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries-extra} + +\newglossaryentry{zebra}{name={zebra},description={stripy animal}} +\newglossaryentry{ant}{name={ant},description={an insect}} + +\begin{document} +\gls{ant} and \gls{zebra} + +\printunsrtglossaries +\end{document} +\end{verbatim} +In the above, zebra will be listed before ant as it was defined +first. + +If you allow document definitions with the \pkgopt{docdefs} option, +the document will require a second \LaTeX\ run if the entries are +defined after \cs{printunsrtglossary}. + +The optional argument is as for \cs{printnoidxglossary} (except for +the \gloskey[printnoidxglossary]{sort} key, which isn't available). + +All glossaries may be displayed in the order of their definition +using: +\begin{definition}[\DescribeMacro\printunsrtglossaries] +\cs{printunsrtglossaries} +\end{definition} +which is analogous to \cs{printnoidxglossaries}. This just +iterates over all defined glossaries (that aren't on the ignored +list) and does \cs{printunsrtglossary}[type=\meta{type}]. + +To avoid complications caused by \env{tabular}-like glossary +styles, \cs{printunsrtglossary} iterates over all entries +in the selected glossary and appends the appropriate code +to an internal command. Once the construction of this +command is complete, then it's performed to display the +glossary. This puts the loop outside the style code. +For convenience, there's a hook used within the loop: +\begin{definition}[\DescribeMacro\printunsrtglossaryentryprocesshook] +\cs{printunsrtglossaryentryprocesshook}\marg{label} +\end{definition} +This hook should not display any content, but may be used +to perform calculations. For example, to calculate widths. +Within this hook you can use: +\begin{definition}[\DescribeMacro\printunsrtglossaryskipentry] +\cs{printunsrtglossaryskipentry} +\end{definition} +to skip the current entry. This will prevent the entry from +being added to the internal command. + +There's another hook immediately before the internal command +containing the glossary code is performed: +\begin{definition}[\DescribeMacro\printunsrtglossarypredoglossary] +\cs{printunsrtglossarypredoglossary} +\end{definition} + +The internal command uses +\begin{definition}[\DescribeMacro\printunsrtglossaryhandler] +\cs{printunsrtglossaryhandler}\marg{label} +\end{definition} +to display each item in the list, where \meta{label} is the current label. + +By default the handler just does +\begin{definition}[\DescribeMacro\glsxtrunsrtdo] +\cs{glsxtrunsrtdo}\marg{label} +\end{definition} +which determines whether to use \cs{glossentry} or +\cs{subglossentry} and checks the \gloskey{location} and +\gloskey{loclist} fields for the \gls{numberlist}. If you want to +use a different field to be used instead of \gloskey{location} +then redefine: +\begin{definition}[\DescribeMacro\GlsXtrLocationField] +\cs{GlsXtrLocationField} +\end{definition} +to the internal name of the desired field. For example: +\begin{verbatim} +\renewcommand{\GlsXtrLocationField}{primarylocation} +\end{verbatim} +\begin{important} +Note that if the given location field is undefined or unset, +the handler will fallback on the \gloskey{loclist} field. +\end{important} +You can instruct \gls{bib2gls} to omit setting the \gloskey{loclist} +field with the resource option \texttt{--save-loclist=false} +to prevent it from being used as a fallback. + +You can redefine the handler if required. For example, +you may want to filter entries according to the category +label. You can test if a label is contained in a comma-separated +list of labels using: +\begin{definition}[\DescribeMacro\glsxtriflabelinlist] +\cs{glsxtriflabelinlist}\marg{label}\marg{label list}\marg{true}\marg{false} +\end{definition} +The \meta{label} and \meta{label list} will be fully expanded. + +\begin{important} +If you redefine the handler to exclude entries, you may end +up with an empty glossary. This could cause a problem for +the list-based styles. +\end{important} + +For example, if the preamble includes: +\begin{verbatim} +\usepackage[record,style=index]{glossaries-extra} +\GlsXtrRecordCounter{section} +\end{verbatim} +then you can print the glossary but first redefine the handler +to only select entries that include the current section number +in the \texttt{record.section} field: +\begin{verbatim} +\renewcommand{\printunsrtglossaryhandler}[1]{% + \glsxtrfieldxifinlist{#1}{record.section}{\thesection} + {\glsxtrunsrtdo{#1}}% + {}% +} +\end{verbatim} + +Alternatively you can use the starred form of +\cs{printunsrtglossary} which will localise the change: + +\begin{verbatim} +\printunsrtglossary*{% + \renewcommand{\printunsrtglossaryhandler}[1]{% + \glsxtrfieldxifinlist{#1}{record.section}{\thesection} + {\glsxtrunsrtdo{#1}}% + {}% + }% +} +\end{verbatim} + +If you are using the \sty{hyperref} package and want to +display the same glossary more than once, you can also +add a temporary redefinition of \cs{glolinkprefix} to +avoid duplicate hypertarget names. For example: + +\begin{verbatim} +\printunsrtglossary*{% + \renewcommand{\printunsrtglossaryhandler}[1]{% + \glsxtrfieldxifinlist{#1}{record.section}{\thesection} + {\glsxtrunsrtdo{#1}}% + {}% + }% + \ifcsundef{theHsection}% + {% + \renewcommand*{\glolinkprefix}{record.\csuse{thesection}.}% + }% + {% + \renewcommand*{\glolinkprefix}{record.\csuse{theHsection}.}% + }% +} +\end{verbatim} +Note that this will cause a problem if your descriptions +contain commands like \cs{gls} that need to link an entry that +doesn't appear in the summary. In this case, it's a better approach +to use: +\begin{verbatim} +\printunsrtglossary*{% + \renewcommand{\printunsrtglossaryhandler}[1]{% + \glsxtrfieldxifinlist{#1}{record.section}{\thesection} + {\glsxtrunsrtdo{#1}}% + {}% + }% + \ifcsundef{theHsection}% + {% + \setkeys{printgloss}{targetnameprefix={record.\csuse{thesection}.}}% + }% + {% + \setkeys{printgloss}{targetnameprefix={record.\csuse{theHsection}.}}% + }% +} +\end{verbatim} + +If it's a short summary at the start of a section, you might +also want to suppress the glossary header and add some vertical +space afterwards: +\begin{verbatim} +\printunsrtglossary*{% + \renewcommand{\printunsrtglossaryhandler}[1]{% + \glsxtrfieldxifinlist{#1}{record.section}{\thesection} + {\glsxtrunsrtdo{#1}}% + {}% + }% + \ifcsundef{theHsection}% + {% + \renewcommand*{\glolinkprefix}{record.\csuse{thesection}.}% + }% + {% + \renewcommand*{\glolinkprefix}{record.\csuse{theHsection}.}% + }% + \renewcommand*{\glossarysection}[2][]{}% + \appto\glossarypostamble{\glspar\medskip\glspar}% +} +\end{verbatim} + +There's a shortcut command that essentially does this: +\begin{definition}[\DescribeMacro\printunsrtglossaryunit] +\cs{printunsrtglossaryunit}\oarg{options}\marg{counter name} +\end{definition} +The above example can simply be replaced with: +\begin{verbatim} +\printunsrtglossaryunit{section} +\end{verbatim} + +This shortcut command is actually defined to use \cs{printunsrtglossary*} with +\begin{definition}[\DescribeMacro\printunsrtglossaryunitsetup] +\cs{printunsrtglossaryunitsetup}\marg{counter name} +\end{definition} +so if you want to just make some minor modifications you can +do +\begin{verbatim} +\printunsrtglossary*{\printunsrtglossaryunitsetup{section}% + \renewcommand*{\glossarysection}[2][]{\subsection*{Summary}}% +} +\end{verbatim} +which will start the list with a subsection header with the +title \qt{Summary} (overriding the glossary's title). + +Note that this shortcut command is only available with the +\pkgopt{record} (or \pkgopt[alsoindex]{record}) package option. + +This temporary change in the hypertarget prefix means you +need to explicitly use \cs{hyperlink} to create a link to it +as commands like \cs{gls} will try to link to the target +created with the default definition of \cs{gloslinkprefix}. +This isn't a problem if you want a primary glossary of all terms +produced using just \cs{printunsrtglossary} (in the front or back +matter) which can be the target for all glossary references +and then just use \cs{printunsrtglossaryunit} for a quick +summary at the start of a section etc. + +\section{Standalone Entry Items} +\label{sec:glossentry} + +It may be that you don't want a list but would rather display +entry details throughout the document. You can simply +do \cs{glsentryname} followed by \cs{glsentrydesc}. +(Remember that if you don't want a sorted list, use +\pkgopt[none]{sort} to skip the construction of the +\gloskey{sort} field.) +For example, in the preamble provide a custom command: +\begin{verbatim} +\newcommand{\displayterm}[1]{% + \par\medskip\par\noindent + Definition: \glsentryname{#1}.\par + \glsentrydesc{#1} + \par\medskip +} +\end{verbatim} +define your entries +\begin{verbatim} +\newglossaryentry{function}{name={function}, + description={a relation or expression involving variables} +} +\end{verbatim} +and then later in the text: +\begin{verbatim} +\displayterm{function} +\end{verbatim} + +However, if may be that you want to use \sty{hyperref} and +have commands like \cs{gls} link back to the place where +the term is described. Instead of using \cs{glsentryname} +use +\begin{definition}[\DescribeMacro\glsxtrglossentry] +\cs{glsxtrglossentry}\marg{label} +\end{definition} +where \meta{label} is the entry's label. + +This is designed to behave much like the way the name is displayed +in the glossary. It performs the following: +\begin{itemize} +\item Defines \cs{glscurrententrylabel} to the entry's label. +This is usually done at the start of the glossary style commands +\cs{glossentry} and \cs{subglossentry} and may be used by hooks, +such as the post-name hooks. Here the definition is localised +so that it's only available for use in \cs{glossentryname}. + +\item Defines \cs{currentglossary} to the entry's glossary type. +This is usually done at the start of commands like +\cs{printglossary} and may be used by style hooks. +Here the definition is localised so that it's only available for use +in \cs{glsentryitem} and \cs{glssubentryitem}. The value is obtained +by fully expanding: +\begin{definition}[\DescribeMacro\GlsXtrStandaloneGlossaryType] +\cs{GlsXtrStandaloneGlossaryType} +\end{definition} +which defaults to the value of the \gloskey{type} field for the +current entry. + +\item Increments and display the entry counters + if the \pkgopt{entrycounter} or \pkgopt{subentrycounter} + package options are set. If the entry doesn't have a parent, then + this does + \begin{itemize} + \item \cs{glsentryitem}\marg{label} + \end{itemize} + otherwise it does (as from v1.31) + \begin{itemize} + \item \ics{GlsXtrStandaloneSubEntryItem}\marg{label} +which defaults to \cs{glssubentryitem}\marg{label} if the entry +has a parent but not a grandparent. + \end{itemize} + This reflects the behaviour of the predefined hierarchical styles. +A bug in pre-version~1.31 used \cs{glsentryitem} for all child levels, +which doesn't match the hierarchical glossary styles. If you want to +restore this behaviour, just do: +\begin{verbatim} +\renewcommand*{\GlsXtrStandaloneSubEntryItem}[1]{\glssubentryitem{#1}} +\end{verbatim} + +\item Sets the hyper-target if supported (using \cs{glstarget}) +and displays the entry name using: +\begin{definition}[\DescribeMacro\GlsXtrStandaloneEntryName] +\cs{GlsXtrStandaloneEntryName}\marg{label} +\end{definition} + which uses + \cs{glstarget}\marg{label}\{\cs{glossentryname}\marg{label}\} + by default. + Remember that \cs{glossentryname} uses \cs{glsnamefont} or picks up + the style from category attributes such as + \catattr{glossnamefont}. +\end{itemize} +If you have used \ics{nopostdesc} or \ics{glsxtrnopostpunc} +in any of your description fields, you can use +\begin{definition}[\DescribeMacro\glsxtractivatenopost] +\cs{glsxtractivatenopost} +\end{definition} +to make these commands behave as they normally do within a glossary. +This needs to be placed before +\begin{alltt} +\cs{glossentrydesc}\marg{label}\cs{glspostdescription} +\end{alltt} +and scoped. Note that \cs{glsnonextpages} and \cs{glsnextpages} have no +effect outside of the glossary and are not intended for use in a +standalone context. + +It's also possible to select a different field (rather than +using \gloskey{name}): +\begin{definition}[\DescribeMacro\glsxtrglossentryother] +\cs{glsxtrglossentryother}\marg{header}\marg{label}\marg{field} +\end{definition} +The \meta{field} must be given using its internal field label +which may not be the same as the key used to set the field. +See the key to field mappings table in the \styfmt{glossaries} +user manual. The \meta{header} argument is the code +to pass to the third argument of \cs{glsxtrtitleorpdforheading}. +It may be left empty in which case the default is determined as follows: +\begin{itemize} +\item If \cs{glsxtrhead\meta{field}} is defined, then \meta{header} +is \cs{glsxtrhead\meta{field}}\marg{label}. +\item Otherwise \meta{header} is simply the field value. +\end{itemize} +The \cs{glsxtrglossentryother} command internally uses +\begin{definition}[\DescribeMacro\GlsXtrStandaloneEntryOther] +\cs{GlsXtrStandaloneEntryOther}\marg{label}\marg{field} +\end{definition} +instead of \cs{GlsXtrStandaloneEntryName}, which uses +\cs{glossentrynameother}\marg{label}\marg{field} instead of +\cs{glossentryname}\marg{label}. + +If you have loaded the +\sty{glossaries-accsupp} package (through the \pkgopt{accsupp} +option) then accessibility support will be provided if +there's a corresponding command +\begin{alltt} +\cs{gls\meta{field}accessdisplay}\marg{text}\marg{label} +\end{alltt} +(for example, \cs{glssymbolaccessdisplay}). + +This means that my custom command can be changed to: +\begin{verbatim} +\newcommand{\displayterm}[1]{% + \par\medskip\par\noindent + Definition: \glsxtrglossentry{#1}.\par + \glsentrydesc{#1} + \par\medskip +} +\end{verbatim} +If I want numbered definitions, then I can use the +package options \sty{entrycounter} or \sty{subentrycounter} +and remove the colon: +\begin{verbatim} +\newcommand{\displayterm}[1]{% + \par\medskip\par\noindent + Definition \glsxtrglossentry{#1}.\par + \glsentrydesc{#1} + \par\medskip +} +\end{verbatim} +The counter label uses a dot after the number by default +but this can be changed to a colon: +\begin{verbatim} +\renewcommand*{\glsentrycounterlabel}{\theglossaryentry:\space} +\end{verbatim} +It's now possible to not only use \cs{gls} to link back to the +definition but also use \cs{glsrefentry} to reference +the counter and \cs{glsxtrpageref} to reference the page number. + +If I want the description to behave more like it does +in a glossary in need to make the following modification: +\begin{verbatim} +\newcommand{\displayterm}[1]{% + \par\medskip\par\noindent + Definition \glsxtrglossentry{#1}.\par + \begingroup + \glsxtractivatenopost + \glossentrydesc{#1}\glspostdescription + \endgroup + \par\medskip +} +\end{verbatim} +(Note the grouping to localise \cs{glsxtractivatenopost}.) + +You can also use \cs{glsxtrglossentry} within section headings. +For example: +\begin{verbatim} +\section{\glsxtrglossentry{function}} +\end{verbatim} +This will use \cs{glsentryname} in PDF bookmarks (if +\cs{texorpdfstring} is defined) and will use \cs{glsxtrheadname} in +page headers and table of contents. (If you're using a page style or +table of contents that doesn't use \cs{markright} or \cs{markbook} +or \cs{@starttoc} then you need to insert \cs{glsxtrmarkhook} and +\cs{@glsxtrinmark} at the start of the header or table of contents +either scoped or afterwards cancelled with \cs{@glsxtrnotinmark} and +\cs{glsxtrrestoremarkhook}.) + +\section{Entry Aliases} +\label{sec:alias} + +An entry can be made an alias of another entry using the +\gloskey{alias} key. The value should be the label of the other +term. There's no check for the other's existence when the aliased +entry is defined. This is to allow the possibility of defining the +other entry after the aliased entry. (For example, when used with +\gls{bib2gls}.) + +If an entry \meta{entry-1} is made an alias of \meta{entry-2} then: +\begin{itemize} +\item If the \gloskey{see} field wasn't provided when \meta{entry-1} +was defined, the \gloskey{alias} key will automatically trigger +\begin{alltt} +\cs{glssee}\marg{entry-1}\marg{entry-2} +\end{alltt} +\item If the \sty{hyperref} package has been loaded then +\cs{gls}\marg{entry-1} will link to \meta{entry-2}'s target. (Unless +the \catattr{targeturl} attribute has been set for \meta{entry-1}'s +category.) +\item With \pkgopt[off]{record} or \pkgopt[alsoindex]{record}, the \gloskey[glslink]{noindex} setting will automatically be triggered +when referencing \meta{entry-1} with commands like \cs{gls} or +\cs{glstext}. This prevents \meta{entry-1} from have a +\gls{locationlist} (aside from the cross-reference added with +\cs{glssee}) unless it's been explicitly indexed with \cs{glsadd} or +if the indexing has been explicitly set using +\texttt{noindex=false}. + +Note that with \pkgopt[only]{record}, the \gls{locationlist} +for aliased entries is controlled with \gls{bib2gls}['s] settings. +\end{itemize} + +The index suppression trigger is performed by +\begin{definition}[\DescribeMacro\glsxtrsetaliasnoindex] +\cs{glsxtrsetaliasnoindex} +\end{definition} +This is performed after the default options provided by +\ics{GlsXtrSetDefaultGlsOpts} have been set. +With \pkgopt[only]{record}, \cs{glsxtrsetaliasnoindex} will +default to do nothing. + +Within the definition of \cs{glsxtrsetaliasnoindex} you can use +\begin{definition}[\DescribeMacro\glsxtrindexaliased] +\cs{glsxtrindexaliased} +\end{definition} +to index \meta{entry-2}. + +The index suppression command can be redefined to index the main +term instead. For example: +\begin{verbatim} +\renewcommand{\glsxtrsetaliasnoindex}{% + \glsxtrindexaliased + \setkeys{glslink}{noindex}% +} +\end{verbatim} + +The value of the \gloskey{alias} field can be accessed using +\begin{definition}[\DescribeMacro\glsxtralias] +\cs{glsxtralias}\marg{label} +\end{definition} + +\chapter{Supplemental Packages} +\label{sec:supplemental} + +The \styfmt{glossaries} bundle provides additional support packages +\sty{glossaries-prefix} (for prefixing) and \sty{glossaries-accsupp} +(for accessibility support). These packages aren't automatically +loaded. + +\section{Prefixes or Determiners} +\label{sec:prefix} + +If prefixing is required, you can simply load +\sty{glossaries-prefix} after \styfmt{glossaries-extra}. For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries-extra} +\usepackage{glossaries-prefix} + +\makeglossaries + +\newabbreviation + [prefix={an\space}, + prefixfirst={a~}] + {svm}{SVM}{support vector machine} + +\begin{document} + +First use: \pgls{svm}. +Next use: \pgls{svm}. + +\printglossaries + +\end{document} +\end{verbatim} + +\section{Accessibility Support} +\label{sec:accsupp} + +The \sty{glossaries-accsupp} package needs to be loaded before +\styfmt{glossaries-extra} or through the \pkgopt{accsupp} package +option: +\begin{verbatim} +\usepackage[accsupp]{glossaries-extra} +\end{verbatim} +If you don't load \sty{glossaries-accsupp} or you load +\sty{glossaries-accsupp} after \styfmt{glossaries-extra} +the new \cs{glsaccess}\meta{xxx} commands described below will +simply be equivalent to the corresponding \cs{glsentry}\meta{xxx} +commands. + +The following \cs{glsaccess}\meta{xxx} commands add accessibility information wrapped around +the corresponding \cs{glsentry}\meta{xxx} commands. There is +no check for existence of the entry nor do any of these commands +add formatting, hyperlinks or indexing information. + +\begin{definition}[\DescribeMacro\glsaccessname] +\cs{glsaccessname}\marg{label} +\end{definition} +This displays the value of the \gloskey{name} field for the entry +identified by \meta{label}. + +If the \sty{glossaries-accsupp} package isn't loaded, this is +simply defined as: +\begin{verbatim} +\newcommand*{\glsaccessname}[1]{\glsentryname{#1}} +\end{verbatim} +otherwise it's defined as: +\begin{verbatim} +\newcommand*{\glsaccessname}[1]{% + \glsnameaccessdisplay + {% + \glsentryname{#1}% + }% + {#1}% +} +\end{verbatim} +(\ics{glsnameaccessdisplay} is defined by the +\sty{glossaries-accsupp} package.) The first letter upper case +version is: +\begin{definition}[\DescribeMacro\Glsaccessname] +\cs{Glsaccessname}\marg{label} +\end{definition} +Without the \sty{glossaries-accsupp} package this is just defined +as: +\begin{verbatim} +\newcommand*{\Glsaccessname}[1]{\Glsentryname{#1}} +\end{verbatim} +With the \sty{glossaries-accsupp} package this is defined as: +\begin{verbatim} +\newcommand*{\Glsaccessname}[1]{% + \glsnameaccessdisplay + {% + \Glsentryname{#1}% + }% + {#1}% +} +\end{verbatim} + +The following commands are all defined in an analogous manner. +\begin{definition}[\DescribeMacro\glsaccesstext] +\cs{glsaccesstext}\marg{label} +\end{definition} +This displays the value of the \gloskey{text} field. + +\begin{definition}[\DescribeMacro\Glsaccesstext] +\cs{Glsaccesstext}\marg{label} +\end{definition} +This displays the value of the \gloskey{text} field with the first +letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccessplural] +\cs{glsaccessplural}\marg{label} +\end{definition} +This displays the value of the \gloskey{plural} field. + +\begin{definition}[\DescribeMacro\Glsaccessplural] +\cs{Glsaccessplural}\marg{label} +\end{definition} +This displays the value of the \gloskey{plural} field +with the first letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccessfirst] +\cs{glsaccessfirst}\marg{label} +\end{definition} +This displays the value of the \gloskey{first} field. + +\begin{definition}[\DescribeMacro\Glsaccessfirst] +\cs{Glsaccessfirst}\marg{label} +\end{definition} +This displays the value of the \gloskey{first} field +with the first letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccessfirstplural] +\cs{glsaccessfirstplural}\marg{label} +\end{definition} +This displays the value of the \gloskey{firstplural} field. + +\begin{definition}[\DescribeMacro\Glsaccessfirstplural] +\cs{Glsaccessfirstplural}\marg{label} +\end{definition} +This displays the value of the \gloskey{firstplural} field +with the first letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccesssymbol] +\cs{glsaccesssymbol}\marg{label} +\end{definition} +This displays the value of the \gloskey{symbol} field. + +\begin{definition}[\DescribeMacro\Glsaccesssymbol] +\cs{Glsaccesssymbol}\marg{label} +\end{definition} +This displays the value of the \gloskey{symbol} field +with the first letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccesssymbolplural] +\cs{glsaccesssymbolplural}\marg{label} +\end{definition} +This displays the value of the \gloskey{symbolplural} field. + +\begin{definition}[\DescribeMacro\Glsaccesssymbolplural] +\cs{Glsaccesssymbolplural}\marg{label} +\end{definition} +This displays the value of the \gloskey{symbolplural} field +with the first letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccessdesc] +\cs{glsaccessdesc}\marg{label} +\end{definition} +This displays the value of the \gloskey{description} field. + +\begin{definition}[\DescribeMacro\Glsaccessdesc] +\cs{Glsaccessdesc}\marg{label} +\end{definition} +This displays the value of the \gloskey{description} field +with the first letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccessdescplural] +\cs{glsaccessdescplural}\marg{label} +\end{definition} +This displays the value of the \gloskey{descriptionplural} field. + +\begin{definition}[\DescribeMacro\Glsaccessdescplural] +\cs{Glsaccessdescplural}\marg{label} +\end{definition} +This displays the value of the \gloskey{descriptionplural} field +with the first letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccessshort] +\cs{glsaccessshort}\marg{label} +\end{definition} +This displays the value of the \gloskey{short} field. + +\begin{definition}[\DescribeMacro\Glsaccessshort] +\cs{Glsaccessshort}\marg{label} +\end{definition} +This displays the value of the \gloskey{short} field with the first +letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccessshortpl] +\cs{glsaccessshortpl}\marg{label} +\end{definition} +This displays the value of the \gloskey{shortplural} field. + +\begin{definition}[\DescribeMacro\Glsaccessshortpl] +\cs{Glsaccessshortpl}\marg{label} +\end{definition} +This displays the value of the \gloskey{shortplural} field with the first +letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccesslong] +\cs{glsaccesslong}\marg{label} +\end{definition} +This displays the value of the \gloskey{long} field. + +\begin{definition}[\DescribeMacro\Glsaccesslong] +\cs{Glsaccesslong}\marg{label} +\end{definition} +This displays the value of the \gloskey{long} field with the first +letter converted to upper case. + +\begin{definition}[\DescribeMacro\glsaccesslongpl] +\cs{glsaccesslongpl}\marg{label} +\end{definition} +This displays the value of the \gloskey{longplural} field. + +\begin{definition}[\DescribeMacro\Glsaccesslongpl] +\cs{Glsaccesslongpl}\marg{label} +\end{definition} +This displays the value of the \gloskey{longplural} field with the first +letter converted to upper case. + +\chapter{Sample Files} +\label{sec:samples} + +The following sample files are provided with this package: +\begin{description} +\item[sample.tex] Simple sample file that uses one of the dummy +files provided by the \styfmt{glossaries} package for testing. + +\item[sample-abbr-styles.tex] Demonstrates all predefined +abbreviation styles. + +\item[sample-mixture.tex] General entries, acronyms and initialisms +all treated differently. + +\item[sample-name-font] Categories and attributes are used to +customize the way different entries appear. + +\item[sample-abbrv.tex] General abbreviations. + +\item[sample-acronym.tex] Acronyms aren't initialisms and don't +expand on \gls{firstuse}. + +\item[sample-acronym-desc.tex] Acronyms that have a separate long +form and description. + +\item[sample-crossref.tex] Unused entries that have been +cross-referenced automatically are added at the end of the document. + +\item[sample-indexhook.tex] Use the index hook to track +which entries have been indexed (and therefore find out +which ones haven't been indexed). + +\item[sample-footnote.tex] Footnote abbreviation style that moves +the footnote marker outside of the hyperlink generated by \cs{gls} +and moves it after certain punctuation characters for neatness. + +\item[sample-undef.tex] Warn on undefined entries instead of +generating an error. + +\item[sample-mixed-abbrv-styles.tex] Different abbreviation styles +for different entries. + +\item[sample-initialisms.tex] Automatically insert dots into +initialisms. + +\item[sample-postdot.tex] Another initialisms example. + +\item[sample-postlink.tex] Automatically inserting text after +the \gls{linktext} produced by commands like \cs{gls} (outside +of hyperlink, if present). + +\item[sample-header.tex] Using entries in section/chapter headings. + +\item[sample-autoindex.tex] Using the \catattr{dualindex} and +\catattr{indexname} attributes to automatically add glossary +entries to the index (in addition to the glossary \gls{locationlist}). + +\item[sample-autoindex-hyp.tex] As previous but uses \sty{hyperref}. + +\item[sample-nested.tex] Using \ics{gls} within the +value of the \gloskey{name} key. + +\item[sample-entrycount.tex] Enable entry-use counting (only index +if used more than $n$ times, see \sectionref{sec:entrycount}). + +\item[sample-unitentrycount.tex] Enable use of per-unit entry-use counting +(\sectionref{sec:entrycount}). + +\item[sample-onelink.tex] Using the per-unit entry counting +(\sectionref{sec:entrycount}) +to only have one hyperlink per entry per page. + +\item[sample-linkcount.tex] Using link counting +(\sectionref{sec:linkcount}) +to only have one hyperlink per entry. + +\item[sample-pages.tex] Insert \qt{page} or \qt{pages} before the +location list. + +\item[sample-altmodifier.tex] Set the default options for +commands like \cs{gls} and add an alternative modifier. + +\item[sample-mixedsort.tex] Uses the optional argument +of \cs{makeglossaries} to allow a mixture of \cs{printglossary} +and \cs{printnoidxglossary}. + +\item[sample-external.tex] Uses the \catattr{targeturl} attribute +to allow for entries that should link to an external URL +rather than to an internal glossary. + +\item[sample-fmt.tex] Provides text-block commands associated +with entries in order to use \cs{glsxtrfmt}. + +\item[sample-alias.tex] Uses the \gloskey{alias} key. +(See \sectionref{sec:alias}.) + +\item[sample-alttree.tex] Uses the \sty{glossaries-extra-stylemods} +package with the \glostyle{alttree} style (see \sectionref{sec:stylemods}). + +\item[sample-alttree-sym.tex] Another \glostyle{alttree} example +that measures the symbol widths. + +\item[sample-alttree-marginpar.tex] Another \glostyle{alttree} example +that puts the \gls{numberlist} in the margin. + +\item[sample-onthefly.tex] Using on-the-fly commands. Terms with +accents must have the \gloskey{name} key explicitly set. + +\item[sample-onthefly-xetex.tex] Using on-the-fly commands +with \XeLaTeX. Terms with UTF-8 characters don't need to +have the \gloskey{name} key explicitly set. Terms that contain +commands must have the \gloskey{name} key explicitly set +with the commands removed from the label. + +\item[sample-onthefly-utf8.tex] Tries to emulate the previous +sample file for use with \LaTeX\ through the starred version +of \ics{GlsXtrEnableOnTheFly}. This is a bit iffy and may not +always work. Terms that contain commands must have the +\gloskey{name} key explicitly set with the commands removed from +the label. + +\item[sample-accsupp.tex] Integrate \sty{glossaries-accsupp}. + +\item[sample-prefix.tex] Integrate \sty{glossaries-prefix}. + +\item[sample-suppl-main.tex] Uses \gloskey[glsadd]{thevalue} to +reference a location in the supplementary file +\texttt{sample-suppl.tex}. + +\item[sample-suppl-main-hyp.tex] A more complicated version to the +above that uses the \sty{hyperref} package to reference a location +in the supplementary file \texttt{sample-suppl-hyp.tex}. + +\end{description} + +\chapter{Multi-Lingual Support} +\label{sec:lang} + +There's only one command provided by \styfmt{glossaries-extra} +that you're likely to want to change in your document and that's +\ics{abbreviationsname} (\sectionref{sec:pkgopts}) if you use +the \pkgopt{abbreviations} package option to automatically +create the glossary labelled \texttt{abbreviations}. If this +command doesn't already exist, it will be defined to +\qt{Abbreviations} if \sty{babel} hasn't been loaded, otherwise +it will be defined as \cs{acronymname} (provided by +\styfmt{glossaries}). + +You can redefine it in the usual way. For example: +\begin{verbatim} +\renewcommand*{\abbreviationsname}{List of Abbreviations} +\end{verbatim} +Or using \sty{babel} or \sty{polyglossia} captions hook: +\begin{verbatim} +\appto\captionsenglish{% + \renewcommand*{\abbreviationsname}{List of Abbreviations}% +} +\end{verbatim} + +Alternatively you can use the \gloskey[printglossary]{title} +key when you print the list of abbreviations. For example: +\begin{verbatim} +\printabbreviations[title={List of Abbreviations}] +\end{verbatim} +or +\begin{verbatim} +\printglossary[type=abbreviations,title={List of Abbreviations}] +\end{verbatim} + +The other fixed text commands are the diagnostic messages, which +shouldn't appear in the final draft of your document. + +The \styfmt{glossaries-extra} package has the facility to load +language modules (whose filename is in the form +\texttt{glossariesxtr-}\meta{language}\texttt{.ldf}) if they exist, +but won't warn if they don't. If \sty{glossaries-extra-bib2gls} is +loaded via the \pkgopt{record} package option then the check for +language resource files will additionally search for an associated +language script file given by +\texttt{glossariesxtr-}\meta{script}\texttt{.ldf} where +\meta{script} is the four letter script identifier, such as +\texttt{Latn}, associated with the given dialect. There's no warning if the +associated file isn't found. The script file is loaded after the +dialect file. + +If you want to write your own language module, you just need to +create a file called +\texttt{glossariesxtr-}\meta{lang}\texttt{.ldf}, where \meta{lang} +identifies the language or dialect (see the \sty{tracklang} +package). For example, \texttt{glossariesxtr-french.ldf}. + +The simplest code for this file is: +\begin{verbatim} +\ProvidesGlossariesExtraLang{french}[2015/12/09 v1.0] + +\newcommand*{\glossariesxtrcaptionsfrench}{% + \def\abbreviationsname{Abr\'eviations}% +} +\glossariesxtrcaptionsfrench + +\ifcsdef{captions\CurrentTrackedDialect} +{% + \csappto{captions\CurrentTrackedDialect}% + {% + \glossariesxtrcaptionsfrench + }% +}% +{% + \ifcsdef{captions\CurrentTrackedLanguage} + {% + \csappto{captions\CurrentTrackedLanguage}% + {% + \glossariesxtrcaptionsfrench + }% + }% + {}% +} +\end{verbatim} + +You can adapt this for other languages by replacing +all instances of the language identifier \texttt{french} and +the translated text \verb|Abr\'eviations| as appropriate. +You can also use the \texttt{.ldf} file to provide rule +blocks for a particular language for use with \gls{bib2gls}['s] custom +sort rule. See \sectionref{sec:bib2glssty} for further details. + +This \texttt{.ldf} file then needs to be put somewhere on \TeX's +path so that it can be found by \styfmt{glossaries-extra}. +You might also want to consider uploading it to CTAN so that +it can be useful to others. (Please don't send it to me. I already +have more packages than I am able to maintain.) + +If you additionally want to provide translations for the diagnostic +messages used when a glossary is missing, you need to redefine +the following commands: +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningHead] +\cs{GlsXtrNoGlsWarningHead}\marg{label}\marg{file} +\end{definition} +This produces the following text in English: +\begin{quote} +\GlsXtrNoGlsWarningHead{\meta{label}}{\meta{file}} +\end{quote} + +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningEmptyStart] +\cs{GlsXtrNoGlsWarningEmptyStart} +\end{definition} +This produces the following text in English: +\begin{quote} +\GlsXtrNoGlsWarningEmptyStart +\end{quote} + +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningEmptyMain] +\cs{GlsXtrNoGlsWarningEmptyMain} +\end{definition} +This produces the following text in English: +\begin{quote} +\GlsXtrNoGlsWarningEmptyMain +\end{quote} + +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningEmptyNotMain] +\cs{GlsXtrNoGlsWarningEmptyNotMain}\marg{label} +\end{definition} +This produces the following text in English: +\begin{quote} +\GlsXtrNoGlsWarningEmptyNotMain{\meta{label}} +\end{quote} + +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningCheckFile] +\cs{GlsXtrNoGlsWarningCheckFile}\marg{file} +\end{definition} +This produces the following text in English: +\begin{quote} +\GlsXtrNoGlsWarningCheckFile{\meta{file}} +\end{quote} + +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningMisMatch] +\cs{GlsXtrNoGlsWarningMisMatch} +\end{definition} +This produces the following text in English: +\begin{quote} +\GlsXtrNoGlsWarningMisMatch +\end{quote} + +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningNoOut] +\cs{GlsXtrNoGlsWarningNoOut}\marg{file} +\end{definition} +This produces the following text in English: +\begin{quote} +\GlsXtrNoGlsWarningNoOut{\meta{file}} +\end{quote} + +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningTail] +\cs{GlsXtrNoGlsWarningTail} +\end{definition} +This produces the following text in English: +\begin{quote} +\GlsXtrNoGlsWarningTail +\end{quote} + +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningBuildInfo] +\cs{GlsXtrNoGlsWarningBuildInfo} +\end{definition} +This is advice on how to generate the glossary files. +See the documented code (\texttt{glossaries-extra-code.pdf}) +for further details. + +\begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningAutoMake] +\cs{GlsXtrNoGlsWarningAutoMake}\marg{label} +\end{definition} +This is the message produced when the \pkgopt{automake} option +is used, but the document needs a rerun or the shell escape +setting doesn't permit the execution of the external application. +This command also generates a warning in the transcript file. +See the documented code for further details. + +\printglossaries +\PrintIndex + +\end{document} |