diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex | 1487 |
1 files changed, 1362 insertions, 125 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex index 56e1c4270cc..b3e18e05929 100644 --- a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex +++ b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex @@ -58,17 +58,22 @@ to run \gls{xindy} or \gls{makeindex} according to the document settings.}} \newglossaryentry{makeglossaries-lite.lua}{% -name={\appfmt{makeglossaries-lite.lua}\index{makeglossaries-lite.lua=\appfmt{makeglossaries-lite.lua}|htextbf}},% -sort={makeglossaries-lite.lua},% -text={\appfmt{makeglossaries-lite.lua}\iapp{makeglossaries-lite.lua}},% +name={\appfmt{makeglossaries-lite}\index{makeglossaries-lite=\appfmt{makeglossaries-lite}|htextbf}},% +sort={makeglossaries-lite},% +text={\appfmt{makeglossaries-lite}\iapp{makeglossaries-lite}},% description={A custom designed Lua script interface to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries} package. This is a cut-down alternative to the Perl \appfmt{makeglossaries} script. If you have Perl installed, use the -Perl script instead. Note that TeX Live creates a symbolic link +Perl script instead. This script is 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.} +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}{% @@ -188,13 +193,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}} \index{glsxtrpostlinkcategory=\cs{glsxtrpostlink}\meta{category}|hyperpage}% } -\newcommand*{\styopt}[2][]{% +\renewcommand*{\pkgopt}[2][]{% \hyperlink{styopt.#2}{\pkgoptfmt{#2}}% \ifstrempty{#1}{}{\pkgoptfmt{=#1}}% \ipkgopt[#1]{#2}% } -\newcommand*{\styoptdef}[1]{% +\newcommand*{\pkgoptdef}[1]{% \htarget{styopt.#1}{\pkgoptfmt{#1}}% \ipkgopt{#1}% } @@ -205,13 +210,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}} \DeleteShortVerb{\|} \MakeShortVerb{"} - \title{glossaries-extra.sty v1.20: + \title{glossaries-extra.sty v1.21: an extension to the glossaries package} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} - \date{2017-09-11} + \date{2017-11-03} \maketitle \begin{abstract} @@ -308,7 +313,7 @@ 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 \styopt{postdot} to restore the +\pkgopt[false]{nopostdot} or just \pkgopt{postdot} to restore the terminating full stop (period). \item \pkgopt[true]{noredefwarn} (suppress the warnings that occur when @@ -497,10 +502,93 @@ The new and modified options provided by \styfmt{glossaries-extra} are described below: \begin{description} -\item[{\styoptdef{postdot}}] (New to version 1.12.) + +\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[{\styoptdef{accsupp}}] Load the \sty{glossaries-accsupp} +\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 @@ -518,15 +606,18 @@ a~package option (not through \ics{glossariesextrasetup}) since the \sty{glossar package must be loaded before \styfmt{glossaries-extra} if it's required. -\item[{\styoptdef{stylemods}}] This is a +\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. +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[{\styoptdef{undefaction}}] This is a \meta{key}=\meta{value} +\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 @@ -541,7 +632,7 @@ over a glossary list. This includes \ics{forglsentries} and \ics{glsaddall}. \end{important} -\item[{\styoptdef{indexcrossrefs}}] This is a boolean option. +\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 @@ -549,7 +640,7 @@ 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 -\styopt[false]{autoseeindex}). To force it off, even if you use the +\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}. @@ -558,7 +649,7 @@ entries when it parses the \texttt{.bib} source file. The \pkgopt{record} option automatically implements \pkgopt[false]{indexcrossrefs}. -\item[{\styoptdef{autoseeindex}}]\label{opt:autoseeindex} (New to +\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 @@ -567,7 +658,7 @@ of those keys will still be stored in their corresponding fields \cs{glsxtruseseealso}) but cross-reference won't be automatically indexed. -Note that the \styopt[only]{record} option automatically implements +Note that the \pkgopt[only]{record} option automatically implements \pkgopt[false]{autoseeindex}. For example, if an entry is defined as @@ -586,7 +677,7 @@ but with \texttt{autoseeindex=false}, this is equivalent to \newglossaryentry{foo}{name={foo},description={}} \GlsXtrSetField{foo}{see}{bar,baz} \end{verbatim} -Note that \styopt{indexcrossrefs} isn't automatically implemented +Note that \pkgopt{indexcrossrefs} isn't automatically implemented by the presence of the \gloskey{see} key when \pkgopt{autoseeindex} is false. @@ -600,22 +691,34 @@ 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[{\styoptdef{record}}]\label{opt:record}(New to v1.08.) This is a \meta{key}=\meta{value} -option, which has three allowed values: \pkgoptfmt{off} (default), -\pkgoptfmt{only} and \pkgoptfmt{alsoindex}. If the value is omitted -\pkgoptfmt{only} is assumed. The option is provided for the benefit -of \gls{bib2gls} (see \sectionref{sec:bib2gls}). +\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. +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}. -The \pkgopt[off]{record} option switches off the recording, as per -the default behaviour. It implements \styopt[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}. + +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} -The other values switch on the recording and also -\styopt[warn]{undefaction}, but \pkgopt[only]{record} -will also switch off the indexing mechanism (even if \cs{makeglossaries} -or \cs{makenoidxglossaries} has been used) whereas -\pkgopt[alsoindex]{record} will both record and index. 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 @@ -627,7 +730,33 @@ the \styfmt{glossaries} package's \pkgopt[none]{sort} option if available. (That option value was only introduced to \styfmt{glossaries} v4.30.) -With the recording on, any of the commands that would typically +\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}). + +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 @@ -636,13 +765,14 @@ out which entries have been used. (Remember that commands like add a corresponding \cs{glsxtr@record} entry to the \texttt{.aux} file.) See \sectionref{sec:bib2gls} for further details. -\item[{\styoptdef{docdef}}] This option governs the use of +\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 three 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 @@ -655,6 +785,14 @@ even if the glossary occurs before \cs{newglossaryentry}. 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 @@ -673,7 +811,7 @@ 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 \styopt[warn]{undefaction} option is used.) If you edit your +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). @@ -702,14 +840,14 @@ This option affects commands that internally use the \qt{on-the-fly} commands described in \sectionref{sec:onthefly}. \end{sloppypar} -\item[{\styoptdef{nomissingglstext}}] This is a boolean option. +\item[{\pkgoptdef{nomissingglstext}}] This is a boolean option. If true, this will suppress 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[{\styoptdef{abbreviations}}] This option has no value and can't +\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 @@ -754,7 +892,7 @@ package's \pkgopt{acronymlists} option (or associated commands) as the abbreviation mechanism is handled differently with \styfmt{glossaries-extra}. -\item[{\styoptdef{symbols}}] This is passed to \styfmt{glossaries} but +\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} @@ -767,7 +905,7 @@ which is equivalent to Note that the \gloskey{sort} key is set to the \meta{label} not the \meta{symbol} as the symbol will likely contain commands. -\item[{\styoptdef{numbers}}] This is passed to \styfmt{glossaries} but +\item[{\pkgoptdef{numbers}}] This is passed to \styfmt{glossaries} but will additionally define \begin{definition}[\DescribeMacro\glsxtrnewnumber] \cs{glsxtrnewnumber}\oarg{options}\marg{number} @@ -778,12 +916,16 @@ which is equivalent to sort=\marg{label},type=numbers,category=number,\meta{options}\} \end{alltt} -\item[{\styoptdef{shortcuts}}] Unlike the \styfmt{glossaries} package +\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}). +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. \item \pkgopt[ac]{shortcuts}: set the shortcuts provided by the \styfmt{glossaries} package for @@ -811,7 +953,7 @@ The \qt{other} shortcuts are: \end{itemize} \item \pkgopt[all]{shortcuts} (or \pkgopt[true]{shortcuts}): -define all the shortcut commands. +implements both \pkgopt[ac]{shortcuts} and \pkgopt[other]{shortcuts} \item \pkgopt[none]{shortcuts} (or \pkgopt[false]{shortcuts}): don't define any of the shortcut commands (default). @@ -826,16 +968,44 @@ set available options using \begin{definition}[\DescribeMacro\glossariesextrasetup] \cs{glossariesextrasetup}\marg{options} \end{definition} -The \styopt{abbreviations} and \styopt{docdef} options may only be -used in the preamble. Additionally, \styopt{docdef} can't be used +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 +\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]{% + \glsifregular{#1}{\glsaccessname{#1}}{\glsaccesstext{#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 commands used by \styfmt{glossaries} to automatically produce an error if an entry is undefined (such as \ics{glsdoifexists}) are -changed to take the \styopt{undefaction} option into account. +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. @@ -951,6 +1121,11 @@ 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 @@ -958,7 +1133,7 @@ for the other glossaries. (See the accompanying file \begin{important} If you use the optional argument \meta{list}, you can't define -entries in the document (even with the \styopt{docdef} option). +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 @@ -1029,6 +1204,38 @@ 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}. \end{description} There is a new hook that's used each time indexing information is @@ -1179,7 +1386,7 @@ This modification allows \styfmt{glossaries-extra} to provide \end{definition} which is used at the end of the document to automatically add any unused cross-references unless the package option -\styopt{indexcrossrefs} was set to false. +\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 @@ -1347,8 +1554,9 @@ 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 will be applied to all linking commands -for all entries. +\ics{glstextformat} which is applied to all linking commands +for all entries, unless overridden by the \catattr{textformat} +attribute. For example: \begin{verbatim} @@ -1360,29 +1568,19 @@ you can query the category: \renewcommand*{\glsxtrregularfont}[1]{% \glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}} \end{verbatim} -or query the category attribute: +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} -or use the attribute to store the control sequence name: +As from version 1.21, it's simpler to just do, for example: \begin{verbatim} -\glssetcategoryattribute{general}{font}{textsf} -\glssetcategoryattribute{acronym}{font}{emph} - -\renewcommand*{\glsxtrregularfont}[1]{% - \glshasattribute{\glslabel}{font}% - {\csuse{\glsgetattribute{\glslabel}{font}}{#1}}% - {#1}% -} +\glssetcategoryattribute{general}{textformat}{textsf} \end{verbatim} -(Remember the category and attribute settings will only queried -here for \catattr{regular} entries, so if the abbreviation style -for the \category{acronym} category in the above example changes -the regular attribute to \qt{false}, \cs{glsxtrregularfont} will -no longer apply.) +without redefining \cs{glsxtrregularfont}. 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 @@ -1625,6 +1823,10 @@ 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 @@ -1660,7 +1862,7 @@ 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 sets lets the \gloskey{plural} field default +\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 @@ -2260,13 +2462,275 @@ 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). + +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}. + +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} +Alternatively you can use the \cs{glsxtrpostname\meta{category}} +hook. + +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} +\ifglsnopostdot,\fi\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 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{Glossary Style Modifications} \label{sec:glosstylemods} -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 \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 @@ -2440,14 +2904,14 @@ passing \meta{name} as a package option to \usepackage{glossaries-extra} \usepackage[longragged]{glossaries-extra-stylemods} \end{verbatim} -Another option is to use the \styopt{stylemods} key when you +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 \styopt{stylemods} may be a comma-separated list +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} @@ -2471,6 +2935,64 @@ 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\glsxtrprelocation] +\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. + +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 \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.05, the \styfmt{glossaries-extra-stylemods} package provides some additional commands for use with the \glostyle{alttree} style to make it easier to modify. @@ -2479,10 +3001,17 @@ These commands are only defined if the 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} (provided by \sty{glossary-tree}) +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] @@ -2498,6 +3027,14 @@ for the top-level entries and \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] @@ -2701,6 +3238,18 @@ fields, which means they won't be used within commands like 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} @@ -2922,8 +3471,8 @@ entry was defined. If you have mixed styles, you'll need to use \label{sec:abbrshortcuts} The abbreviation shortcut commands can be enabled using -the package option \styopt[abbreviation]{shortcuts} -(or \styopt[abbr]{shortcuts}) or \styopt[ac]{shortcuts}. +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}. @@ -3254,12 +3803,14 @@ The new naming scheme for abbreviation styles is as follows: 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{field2} starts with \qt{no} -then the parenthetical element is omitted from the display style but -is included in the inline style. +\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. +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. @@ -3377,24 +3928,40 @@ 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}). + \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 and the \gloskey{description} must be supplied by the @@ -3692,6 +4259,10 @@ supplied in the optional argument of \cs{newabbreviation} 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} @@ -4524,7 +5095,7 @@ 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}. If you don't like this +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} @@ -4536,6 +5107,10 @@ 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 @@ -4661,6 +5236,18 @@ and \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] @@ -4709,9 +5296,9 @@ 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 \styopt{symbols} package +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 \styopt{numbers} package +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 @@ -4974,7 +5561,7 @@ 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{glossentyname} +used at the end of \ics{glossentryname} will index the entry using \ics{index}. See \sectionref{sec:autoindex} for further details. @@ -4994,6 +5581,21 @@ 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 @@ -5233,7 +5835,7 @@ commands like \ics{cgls} will generate a warning if shortcut \ics{ab} uses \cs{cgls} (see \sectionref{sec:abbrshortcuts}) unlike the acronym shortcut \ics{ac} which uses \cs{gls} (except when it's defined through -\styopt[ac]{shortcuts}). +\pkgopt[ac]{shortcuts}). All upper case versions (not provided by \styfmt{glossaries}) are also available: @@ -5734,12 +6336,12 @@ 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 \styopt{docdefs} package options. +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 -\styopt{docdefs} option. \emph{There are limitations with this +\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] @@ -5932,7 +6534,7 @@ preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"} \end{verbatim} To ensure that \gls{bib2gls} can find out which entries have been -used in the document, you need the \styopt{record} package option: +used in the document, you need the \pkgopt{record} package option: \begin{verbatim} \usepackage[record]{glossaries-extra} \end{verbatim} @@ -5942,7 +6544,7 @@ collate the locations. If you still want to use an indexing application (for example, you need a custom \gls{xindy} rule), then just use -\styopt[alsoindex]{record} and continue to use \cs{makeglossaries} +\pkgopt[alsoindex]{record} and continue to use \cs{makeglossaries} and \cs{printglossary} (or \cs{printglossaries}), but it's a good idea to also instruct \gls{bib2gls} to omit sorting to save time. @@ -5983,8 +6585,8 @@ 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} won't exist on the first \LaTeX\ run, the -\styopt{record} package option additionally switches on -\styopt[warn]{undefaction}. Any use of commands like \cs{gls} or +\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 they are undefined at this point. Once \gls{bib2gls} has created the \texttt{.glstex} file the references should be resolved. @@ -5992,8 +6594,34 @@ This may cause a shift in the locations if the actual text produced once the entry is defined is larger than the placeholder ?? (as can occur with long citations). +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, 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 \cs{glsaddall} doesn't work with \gls{bib2gls} as the command +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}. @@ -6005,16 +6633,38 @@ options list. For example: \begin{verbatim} \GlsXtrLoadResources[src={terms},selection={all}] \end{verbatim} -See the \gls{bib2gls} user manual for more details of this and other -available options. - -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. - -Since the \texttt{.glstex} file only defines those references used -within the document and the definitions have been written in the +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. +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} sorted list, the glossaries can simply be displayed using \cs{printunsrtglossary} (or \cs{printunsrtglossaries}), described in \sectionref{sec:printunsrt}. @@ -6076,13 +6726,11 @@ different sort methods: \GlsXtrLoadResources[src={terms},sort={en-GB},type=main] -\glsxtrresourcefile +\GlsXtrLoadResources [src={abbrvs},sort={letter-nocase},type=abbreviations] - {\jobname-abr} -\glsxtrresourcefile +\GlsXtrLoadResources [src={symbols},sort={use},type={symbols}] - {\jobname-sym} \begin{document} \gls{bird} @@ -6094,11 +6742,434 @@ different sort methods: \printunsrtglossaries \end{document} \end{verbatim} -(By default, entries are sorted according to the operating system's -locale. If this doesn't match the document language, you need to -set this in the option list, for example \verb|sort=de-CH-1996| -for Swiss German using the new orthography.) +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} + +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}, +may have Unicode characters indicated in the format +\cs{u}\meta{hex} \emph{in the \texttt{.aux} file}. \gls{bib2gls} +will recognise this format as indicating 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 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{string}\cs{u}E6;\cs{string}\cs{u}C6 < a;\cs{string}\cs{u}E1;\cs{string}\cs{u}E5,\cs{string}\cs{u}E4,A;\cs{string}\cs{u}C1;\cs{string}\cs{u}C5;\cs{string}\cs{u}C4 < b,B + < c;\cs{string}\cs{u}0107,C;\cs{string}\cs{u}0106 < d,D < e;\cs{string}\cs{u}E9,E;\cs{string}\cs{u}C9 < f,F < g,G + < h,H < i;\cs{string}\cs{u}ED,I;\cs{string}\cs{u}CD < j,J < l;\cs{string}\cs{u}0142,L;\cs{string}\cs{u}0141 < m,M < n,N + < o;\cs{string}\cs{u}F6;\cs{string}\cs{u}F8,O;\cs{string}\cs{u}D6;\cs{string}\cs{u}D8 < p,P < q,Q < r,R < s;\cs{string}\cs{u}013F,S;\cs{string}\cs{u}015A + < t,T < u;\cs{string}\cs{u}FA,U;\cs{string}\cs{u}DA < v,V < w,W < x,X < y,Y < + z;\cs{string}\cs{u}017C,Z;\cs{string}\cs{u}017B + } +] +\end{alltt} + +\section{Supplementary Commands} + +These commands are provided by \styfmt{glossaries-extra} +for use with \gls{bib2gls}. + +\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 described above). + +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|\uE6| 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. + +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} +does 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},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} + +\section{Record Counting} + +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} @@ -6190,7 +7261,7 @@ command to an argument: \end{definition} This effectively does \begin{alltt} -\cs{glslink}\oarg{options}\marg{label}\marg{\meta{cs}\marg{text}} +\cs{glslink}\oarg{options}\marg{label}\{\meta{cs}\marg{text}\} \end{alltt} where \meta{cs} is the command obtained from the control sequence name supplied in the provided field. If the field @@ -6285,7 +7356,7 @@ 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 \styopt[warn]{undefaction}. You can redefine +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] @@ -6358,6 +7429,19 @@ The starred version \end{definition} omits the implicit grouping. +You can test if a field value equals a string using +\begin{definition}[\DescribeMacro{\GlsXtrIfFieldEqStr}] +\cs{GlsXtrIfFieldEqStr}\marg{label}\marg{field}\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 is just a shortcut that 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}. + + 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 @@ -6422,7 +7506,7 @@ See the \sty{etoolbox}'s user manual for further details of these commands, in particular the limitations of \cs{ifinlist}. -When using the \styopt{record} option, in addition to recording the +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] @@ -6464,6 +7548,11 @@ iterated over with \cs{glsxtrfielddolistloop} etc. 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*}] @@ -6495,7 +7584,7 @@ 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 -\styopt[only]{record} package option will automatically deal with +\pkgopt[only]{record} package option will automatically deal with this. For example: @@ -6516,7 +7605,7 @@ For example: In the above, zebra will be listed before ant as it was defined first. -If you allow document definitions with the \styopt{docdefs} option, +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}. @@ -6532,13 +7621,38 @@ 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}]. -The \cs{printunsrtglossary} command internally uses +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} -for each item in the list, where \meta{label} is the current label. +to display each item in the list, where \meta{label} is the current label. -By default this just does +By default the handler just does \begin{definition}[\DescribeMacro\glsxtrunsrtdo] \cs{glsxtrunsrtdo}\marg{label} \end{definition} @@ -6546,7 +7660,14 @@ which determines whether to use \cs{glossentry} or \cs{subglossentry} and checks the \gloskey{location} and \gloskey{loclist} fields for the \gls{numberlist}. -You can redefine the handler if required. +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 @@ -6671,7 +7792,7 @@ 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 -\styopt{record} (or \styopt[alsoindex]{record}) package option. +\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 @@ -6683,6 +7804,122 @@ 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 Definitions} +\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}. + +\item Increments and display the entry counters + if the \pkgopt{entrycounter} or \pkgopt{subentrycounter} + package options are set. If the entry has a parent, then + this does + \begin{itemize} + \item \cs{glssubentryitem}\marg{label} + \end{itemize} + otherwise it does + \begin{itemize} + \item \cs{glsentryitem}\marg{label} + \end{itemize} + +\item Sets the hyper-target if supported (using \cs{glstarget}). + +\item Displays the entry name using + \cs{glossentryname}\marg{label}. + Remember that this command uses \cs{glsnamefont} or picks up + the style from category attributes such as + \catattr{glossnamefont}. +\end{itemize} + +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 you wanted numbered definitions, then use the +package option \sty{entrycounter} 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} +You can now 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. + +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} @@ -6704,7 +7941,7 @@ was defined, the \gloskey{alias} key will automatically trigger \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 \styopt[off]{record} or \styopt[alsoindex]{record}, the \gloskey[glslink]{noindex} setting will automatically be triggered +\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 @@ -6712,7 +7949,7 @@ when referencing \meta{entry-1} with commands like \cs{gls} or if the indexing has been explicitly set using \texttt{noindex=false}. -Note that with \styopt[only]{record}, the \gls{locationlist} +Note that with \pkgopt[only]{record}, the \gls{locationlist} for aliased entries is controlled with \gls{bib2gls}['s] settings. \end{itemize} @@ -6722,7 +7959,7 @@ The index suppression trigger is performed by \end{definition} This is performed after the default options provided by \ics{GlsXtrSetDefaultGlsOpts} have been set. -With \styopt[only]{record}, \cs{glsxtrsetaliasnoindex} will +With \pkgopt[only]{record}, \cs{glsxtrsetaliasnoindex} will default to do nothing. Within the definition of \cs{glsxtrsetaliasnoindex} you can use @@ -6784,8 +8021,8 @@ Next use: \pgls{svm}. \section{Accessibility Support} \label{sec:accsupp} -The \sty{glossaries-accsupp} needs to be loaded before -\styfmt{glossaries-extra} or through the \styopt{accsupp} package +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} @@ -7112,7 +8349,7 @@ in the supplementary file \texttt{sample-suppl-hyp.tex}. 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 \styopt{abbreviations} package option to automatically +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 |