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 | 2526 |
1 files changed, 1471 insertions, 1055 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 674b7047221..28bd4c59a55 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 @@ -1,4 +1,4 @@ -\documentclass[report,inlinetitle,widecs]{nlctdoc} +\documentclass[report,inlinetitle,noprint]{nlctdoc} \makeatletter \@ifpackageloaded{tex4ht} @@ -225,13 +225,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}} \DeleteShortVerb{\|} \MakeShortVerb{"} - \title{glossaries-extra.sty v1.41: + \title{glossaries-extra.sty v1.42: an extension to the glossaries package} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} - \date{2019-04-09} + \date{2020-02-13} \maketitle \begin{abstract} @@ -241,7 +241,7 @@ 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 +The file \nolinkurl{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, @@ -611,9 +611,17 @@ missing. (With \gls{bib2gls} you can instead redefine 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} +\item[{\pkgoptdef{prefix}}] Load the \sty{glossaries-prefix} package (if not already loaded). +\item[{\pkgoptdef{accsupp}}] Load the \sty{glossaries-accsupp} +package (if not already loaded). + +\begin{important} +The \sty{glossaries-accsupp} package is still experimental and so +accessibility features are liable to change. +\end{important} + 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 @@ -1009,7 +1017,9 @@ file or files. 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 +label. (The file extensions are \filetype{glg-abr}, +\filetype{gls-abr} and \filetype{glo-abr}.) +In addition, this option defines a shortcut command \begin{definition}[\DescribeMacro\printabbreviations] \cs{printabbreviations}\oarg{options} \end{definition} @@ -1180,6 +1190,8 @@ after \ics{makenoidxglossaries}. \chapter{Modifications to Existing Commands and Styles} \label{sec:modifications} +\section{Defining Entries} + 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 @@ -1202,95 +1214,10 @@ 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 @@ -1303,11 +1230,14 @@ entry. See \sectionref{sec:alias} for further details. 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 +This apply to all entry defining commands (such as +\cs{newabbreviation}). + +The test file \nolinkurl{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 +There are also \nolinkurl{example-glossaries-*.bib} files that +correspond to each \nolinkurl{example-glossaries-*.tex} file for testing \gls{bib2gls}. The \cs{longnewglossaryentry} command now has a starred version @@ -1444,6 +1374,7 @@ equivalent to: \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} @@ -1491,8 +1422,8 @@ which is defined as: } \end{verbatim} This sets the conditional -\begin{definition}[\DescribeMacro\ifglsxtrinitwrglossbefore] -\cs{ifglsxtrinitwrgloss} +\begin{definition} +\ics{ifglsxtrinitwrgloss} \end{definition} which is used to determine where to perform the indexing. @@ -1555,6 +1486,77 @@ hyperlink location (see below). \end{description} +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. + There is a new hook that's used each time indexing information is written to the external glossary files: \begin{definition}[\DescribeMacro\glsxtrdowrglossaryhook] @@ -1813,7 +1815,44 @@ sub-entries. For example: \renewcommand*{\glsseeitemformat}[1]{\glsxtrhiername{#1}} \end{verbatim} -The command: +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}{\glsfmttext{#1}}{\glsfmtname{#1}}% +} +\end{verbatim} +(Note that as from \styfmt{glossaries-extra} version 1.42, this now +uses \cs{glsfmttext} and \cs{glsfmtname} instead of just referencing +the \gloskey{text} and \gloskey{name} fields. This helps to ensure +that any formatting is correctly applied.) + +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. \begin{definition}[\DescribeMacro\glsxtrhiername] \cs{glsxtrhiername}\marg{label} \end{definition} @@ -1824,8 +1863,8 @@ performs a recursive action: \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}). +the short form is displayed (using \cs{glsfmtshort}) +otherwise the name is displayed (using \cs{glsfmtname}). \end{enumerate} The first step above is skipped if the entry doesn't have a parent. Each level is separated by: @@ -1840,27 +1879,27 @@ There are some case-changing variants: \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 +(either \cs{Glsfmtshort} or \cs{Glsfmtname}). 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}). +(either \cs{Glsfmtshort} or \cs{Glsfmtname}). \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 +(either \cs{GLSfmtshort} or \cs{GLSfmtname}). 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}). +(either \cs{GLSfmtshort} or \cs{GLSfmtname}). Suppose you want to suppress the \gls*{numberlist} using \pkgopt{nonumberlist}. This will automatically prevent the @@ -1912,6 +1951,13 @@ For example: } \end{verbatim} +The \gloskey{alias} key only contains a single label not a list, but +if you want to ensure consistent formatting with \cs{glsxtrusesee} +and \cs{glsxtruseseealso} you can use (from v1.42): +\begin{definition}[\DescribeMacro\glsxtrusealias] +\cs{glsxtrusealias}\marg{label} +\end{definition} + The actual unformatted comma-separated list \meta{xr-list} stored in the \gloskey{seealso} field can be accessed with: \begin{definition}[\DescribeMacro\glsxtrseealsolabels] @@ -1946,6 +1992,21 @@ 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. +The command that produces this \qt{see also} text is +\begin{definition}[\DescribeMacro\seealsoname] +\cs{seealsoname} +\end{definition} +If \ics{alsoname} (provided by language packages) is defined then +\cs{seealsoname} will simply be defined to \cs{alsoname} otherwise +it will be defined to \texttt{see also}. + +The language-sensitive \cs{alsoname} is used by general indexing +packages, such as \sty{makeidx}, so if you redefine \cs{alsoname} +the change will apply to normal indexes as well as glossaries. If +you only want to change the text produced by the \gloskey{seealso} +key without affecting general indexing (with \cs{index}) then +redefine \cs{seealsoname} instead. + \section{Entry Display Style Modifications} \label{sec:entryfmtmods} @@ -1959,8 +2020,9 @@ 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: +\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 @@ -2178,141 +2240,6 @@ 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} @@ -2457,6 +2384,12 @@ 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. +You can discard the buffer and restore \cs{glsunset} to its normal +behaviour with (new to v1.42): +\begin{definition}[\DescribeMacro\GlsXtrDiscardUnsetBuffering] +\cs{GlsXtrDiscardUnsetBuffering} +\end{definition} + \begin{important} Note that since the change in the first use flag now doesn't occur until \cs{GlsXtrStopUnsetBuffering}, multiple references @@ -2995,7 +2928,16 @@ The simplest way to update a document that uses \begin{verbatim} \setabbreviationstyle[acronym]{long-short} \end{verbatim} -before you define any entries. +before you define any entries. If you have used commands like +\ics{acrshort}, \ics{acrlong} and \ics{acrfull}, you need to +substitute them with \ics{glsxtrshort}, \ics{glsxtrlong} and +\ics{glsxtrfull}. (This includes plural and case-changing forms.) +Your text editor's search and replace function should help with +this. If you have used the \pkgopt{shortcuts} package option then +use \pkgopt[ac]{shortcuts} in order to continue using the shortcut +commands like \ics{ac}. With this setting, \ics{acs} will use +\ics{glsxtrshort} instead of \ics{acrshort} etc. + For example, the following document using just \styfmt{glossaries} \begin{verbatim} \documentclass{article} @@ -3129,6 +3071,812 @@ is redefined to use the subsequent use abbreviation font command \ics{glsabbrvfont}. This will be reset if you use \cs{RestoreAcronyms}. +\section{Glossaries} + +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 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} + +\subsection{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} + +\subsubsection{Style Hooks} +\label{sec:stylehooks} + +The commands \ics{glossentryname} and \ics{glossentrydesc} are +modified to take into account the \catattr{glossname}, +\category{glossnamefont}, \catattr{glossdesc} and \catattr{glossdescfont} +attributes (see \sectionref{sec:categories}). This means you can +make simple font or case-changing modifications to the name and description +without defining a new glossary style. + +(New to version 1.42.) +The command \ics{glossentrysymbol} is modified to take into account +the \catattr{glosssymbolfont}. Note that, unlike the above, there's +no corresponding attribute to change the case as it's usually not +appropriate to change the case of a symbol (and for some symbols, +such as pictographs, there's no concept of case). If +\ics{texorpdfstring} has been defined \ics{glossentrysymbol} will +be defined to do: +\begin{alltt} +\ics{texorpdfstring}\marg{\TeX\ code}\marg{PDF} +\end{alltt} +The \meta{\TeX\ code} part is robust and deals with the actual +typesetting of the symbol. The \meta{PDF} part is simply: +\begin{definition}[\DescribeMacro\glsentrypdfsymbol] +\cs{glsentrypdfsymbol}\marg{label} +\end{definition} +which is defined to just do \cs{glsentrysymbol}\marg{label}. The +chances are that the code in the \gloskey{symbol} key won't be valid +in the PDF bookmarks, so you can redefine \cs{glsentrypdfsymbol} to +use a more appropriate field. (If you do redefine this command, +remember that it needs to fully expand.) + +For example, if you are using \sty{glossaries-accsupp}, you could +use the \gloskey{symbolaccess} field: +\begin{verbatim} +\renewcommand{\glsentrypdfsymbol}[1]{\glsentrysymbolaccess{#1}} +\end{verbatim} +Alternatively, if you are using \gls{bib2gls} you can use the \TeX\ +parser library to interpret a copy of the \gloskey{symbol} field and +use that. For example, with the resource options: +\begin{verbatim} + replicate-fields={symbol=user1}, + interpret-fields={user1} +\end{verbatim} +This stores the interpreted value of the symbol in the +\gloskey{user1} field, so you can then do: +\begin{verbatim} +\renewcommand{\glsentrypdfsymbol}[1]{\glsentryuseri{#1}} +\end{verbatim} +(You may need \XeLaTeX\ or \LuaLaTeX\ with this method.) This allows +\cs{glossentrysymbol} to be used in a section heading with +standalone definitions. + +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} + +\subsubsection{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} + +For example, to change the font for the entire +\gls{numberlist} 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}. + +\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. + +\subsubsection{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 new commands in +v4.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 without headers is given by: +\begin{definition}[\DescribeMacro\glstreegroupskip] +\cs{glstreegroupskip} +\end{definition} +This defaults to just \ics{indexspace} without penalties. This +command isn't used if \pkgopt{nogroupskip} is set. (The penalties +introduced in v1.41 were moved to \cs{glstreeheadergroupskip} in +v1.42 as they are inappropriate when there's no header.) + +The separator between groups with headers is now given by (as from v1.42): +\begin{definition}[\DescribeMacro\glstreeheadergroupskip] +\cs{glstreegroupheaderskip} +\end{definition} +This defaults to \cs{glstreegroupskip} with penalties to deter page +breaks after the group heading. + +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 what separator to use +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. + +If either the symbol or description is present these will use +\cs{glstreeprelocation} or \cs{glstreechildprelocation}, +respectively. Otherwise, both will use (from v1.42): +\begin{definition}[\DescribeMacro\glstreeNoDescSymbolPreLocation] +\cs{glstreeNoDescSymbolPreLocation} +\end{definition} +The default is a space. This means that you could have, say, a +comma followed by a space for terms that are simply an alias, but +just have a space for terms that have a description that ends with a +full stop (or that just have a symbol without a description) where +the comma would be inappropriate. + +Note that version 1.42 has corrected an error that was introduced to +v1.41 that caused the name to run into the location list if there +was no symbol and no description. + +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 +(\nolinkurl{glossaries-extra-code.pdf}). See also +the accompanying sample files \nolinkurl{sample-alttree.tex}, +\nolinkurl{sample-alttree-sym.tex} and +\nolinkurl{sample-alttree-marginpar.tex}. + +\chapter{New Glossary Styles} + +The \styfmt{glossaries-extra} package comes with some new styles. +The associated style package needs to be loaded. This can be done +with \cs{usepackage} but it's simpler to use the \pkgopt{stylemods} +option. + \section{\styfmt{glossary-bookindex} package} \label{sec:bookindex} @@ -4093,624 +4841,6 @@ Finally the location list is displayed using: \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} @@ -4722,17 +4852,50 @@ package modifies the underlying formatting used by 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. +See the file +\href{http://mirrors.ctan.org/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.pdf}{sample-abbr-styles.pdf} +for samples of all provided abbreviation styles. \begin{important} -Don't use commands like \cs{glstext} or \cs{glsfirst} with +Don't use \ics{glsfirst}, \ics{Glsfirst} or \ics{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 +abbreviation styles and unexpected results may occur. (To a lesser +degree, this also applies to \ics{glstext} etc.) Use commands +like \cs{glsfmttext}, \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} +This lack of flexibility in \cs{glsfirst} can be demonstrated with +the following document: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries-extra} +\setabbreviationstyle{footnote} +\newabbreviation{ex}{EX}{Example} + +\begin{document} +Compare \gls{ex}['s] with \glsfirst{ex}['s]. +\end{document} +\end{verbatim} +The \gls{firstuse} \cs{gls} has the footnote marker after the +inserted material \qt{EX's\textsuperscript{1}} but \cs{glsfirst} has +it before the inserted material \qt{EX\textsuperscript{1}'s} which +is inappropriate. Note that if the style is changed to +\abbrstyle{postfootnote}, the footnote marker appears after the +inserted material as \ics{footnote} is in the post-link hook. + +There are some instances where \cs{glstext} can be useful. It's used +internally by \ics{glsfmttext}, which in turn is used by +\ics{glsseelistformat} if the entry has a short form. If +\cs{glsfmtshort} is used, this enforces the short form, but if +\cs{glsfmttext} is used, then the long form will be used for the +\qt{noshort} styles, which is more appropriate. In this particular +situation, there's no need to worry about inserted material as the +final optional argument isn't supported by \cs{glsfmttext}. + Abbreviations include acronyms (words formed from initial letters, such as \qt{laser}), initialisms (initial letters of a phrase, such as \qt{html}, that @@ -4826,6 +4989,17 @@ use by the long form: \cs{glsuselongfont}\marg{text}\marg{category} \end{definition} +You can't use the acronym commands provided by the base package with +the new abbreviations provided by the \styfmt{glossaries-extra} +package. The style commands that replace \cs{setacronymstyle}, +\cs{acrshort} etc are described in \sectionref{sec:abbrstyle}. +The \pkgopt{acronymlists} package option and associated commands +aren't supported. The \ics{forallacronyms} command, which iterates +over all acronym lists, should be replaced with: +\begin{definition}[\DescribeMacro\forallabbreviationlists] +\cs{forallabbreviationlists}\marg{cs}\marg{body} +\end{definition} + \section{Tagging Initials} \label{sec:tagging} @@ -4866,7 +5040,7 @@ 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} +The accompanying sample file \nolinkurl{sample-mixtures.tex} uses initial tagging for both the \category{acronym} and \category{abbreviation} categories: \begin{verbatim} @@ -5047,7 +5221,7 @@ 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 \pkgopt[abbreviation]{shortcuts} +the \pkgopt[abbreviations]{shortcuts} package option (or \pkgopt[abbr]{shortcuts}) or \pkgopt[ac]{shortcuts}. (You can use both settings at the same time.) The provided shortcut commands listed in @@ -5120,7 +5294,7 @@ 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 +The sample file \nolinkurl{sample-abbr-styles.tex} demonstrates all predefined styles described here. \begin{important} @@ -5131,6 +5305,15 @@ recommend that you at least use the \sty{fontenc} package with the \pkgoptfmt{T1} option or something similar. \end{important} +Many of the styles have helper commands in the form +\cs{glsxtr...name} and \cs{glsxtr...sort} that are expanded within the +\gloskey{name} and \gloskey{sort} fields when the abbreviation is defined. +These commands may use the helper token registers available within +\cs{newabbreviation}, such as \ics{glsshorttok}. The contents of a +register can be accessed with \ics{the}\meta{register}. It's essential that +these expand when the abbreviation is defined so don't hide them behind no-expandable content if you +redefine these helper commands. + The parenthetical styles, such as \abbrstyle{long-short}, use \begin{definition}[\DescribeMacro\glsxtrparen] @@ -6059,7 +6242,7 @@ 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 +\gloskey{name} key is obtained by expanding: \begin{definition}[\DescribeMacro\glsxtrfootnotename] \cs{glsxtrfootnotename} \end{definition} @@ -6126,6 +6309,44 @@ use \ics{glsabbrvemfont}. 1.04, but original name retained as a deprecated synonym for backward-compatibility.) +\item[\abbrstyledef{short-footnote-desc}] +(New to v1.42.) +This is similar to \abbrstyle{short-footnote}, but the +\gloskey{description} must be supplied by the user. +The \gloskey{name} field is obtained from: +\begin{definition}[\DescribeMacro\glsxtrfootnotedescname] +\cs{glsxtrfootnotedescname} +\end{definition} +which defaults to \meta{short} followed by \meta{long} in +parentheses, and the \gloskey{sort} field is obtained from: +\begin{definition}[\DescribeMacro\glsxtrfootnotedescsort] +\cs{glsxtrfootnotedescsort} +\end{definition} +which defaults to just the short form. (Similarly for other +\texttt{short}\meta{modifier}\texttt{-[post]footnote}\texttt{-desc} +styles, unless indicated otherwise.) + +Any redefinition of these commands 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{footnote-desc}] +A synonym for \abbrstyle{short-footnote-desc}. + +\item[\abbrstyledef{short-sc-footnote-desc}] +Like \abbrstyle{short-footnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. + +\item[\abbrstyledef{short-sm-footnote-desc}] +Like \abbrstyle{short-footnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. + +\item[\abbrstyledef{short-em-footnote-desc}] +Like \abbrstyle{short-footnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + \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 @@ -6165,6 +6386,28 @@ use \ics{glsabbrvemfont}. 1.04, but original name retained as a deprecated synonym for backward-compatibility.) +\item[\abbrstyledef{short-postfootnote-desc}] +(New to v1.42.) +This is similar to \abbrstyle{short-postfootnote}, but the +\gloskey{description} must be supplied by the user. The +\gloskey{name} and \gloskey{sort} are set as for +\abbrstyle{short-footnote-desc}. + +\item[\abbrstyledef{postfootnote-desc}] +A synonym for \abbrstyle{short-postfootnote-desc}. + +\item[\abbrstyledef{short-sc-postfootnote-desc}] +Like \abbrstyle{short-postfootnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. + +\item[\abbrstyledef{short-sm-postfootnote-desc}] +Like \abbrstyle{short-postfootnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. + +\item[\abbrstyledef{short-em-postfootnote-desc}] +Like \abbrstyle{short-postfootnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + \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 @@ -6771,7 +7014,7 @@ 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}). +(\nolinkurl{glossaries-extra-code.pdf}). \chapter{Entries in Sectioning Titles, Headers, Captions and Contents} \label{sec:headtitle} @@ -6800,6 +7043,8 @@ in the table of contents. Similar problems can also occur with captions (except for the page header and bookmark issues). +\section{Simplistic Approach} + 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} @@ -6859,14 +7104,22 @@ 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. +\section{New Commands Designed for Chapter/Section Headings} + +The commands listed below are designed for use in chapter or section +headings. There are still limitations, but they provide a better +solution. They 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. If the required field contains +non-expandable (robust or fragile) commands that cause a problem for +the bookmarks then \ics{texorpdfstring} will be needed as +appropriate in that field. (Take care if the field has its value +expanded before being assigned.) These commands essentially behave as though you have used -\cs{glsxtrshort} (or equivalent) with the options +\cs{glsxtrshort}, \cs{glstext} etc 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 @@ -6908,6 +7161,18 @@ First letter upper case plural short form: \end{definition} (No case-change applied to PDF bookmarks.) +All caps singular short form: +\begin{definition}[\DescribeMacro\GLSfmtshort] +\cs{GLSfmtshort}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +All caps 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} @@ -6930,9 +7195,32 @@ First letter upper case plural long form: \end{definition} (No case-change applied to PDF bookmarks.) +All caps singular long form: +\begin{definition}[\DescribeMacro\GLSfmtlong] +\cs{GLSfmtlong}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +All caps 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}. +full form used by \cs{gls}. The PDF version has to be a simple +fully expandable command, so one of two commands that are unrelated to the style +is used instead: +\begin{definition}[\DescribeMacro\glspdffmtfull] +\cs{glspdffmtfull}\marg{label} +\end{definition} +for the singular form or: +\begin{definition}[\DescribeMacro\glspdffmtfullpl] +\cs{glspdffmtfullpl}\marg{label} +\end{definition} +for the full form. These simply do the long form followed by the +short form in parentheses. Display the full form: \begin{definition}[\DescribeMacro\glsfmtfull] @@ -6956,6 +7244,18 @@ First letter upper case plural full form: \end{definition} (No case-change applied to PDF bookmarks.) +All caps singular full form: +\begin{definition}[\DescribeMacro\GLSfmtfull] +\cs{GLSfmtfull}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +All caps 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] @@ -6968,14 +7268,24 @@ First letter converted to upper case: \end{definition} (No case-change applied to PDF bookmarks.) +All caps: +\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 +First letter upper case: \begin{definition}[\DescribeMacro\Glsfmtplural] \cs{Glsfmtplural}\marg{label} \end{definition} +and all caps: +\begin{definition}[\DescribeMacro\GLSfmtplural] +\cs{GLSfmtplural}\marg{label} +\end{definition} Likewise for the value of the \gloskey{name} field: @@ -6989,6 +7299,12 @@ First letter converted to upper case: \end{definition} (No case-change applied to PDF bookmarks.) +All caps: +\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] @@ -7001,14 +7317,24 @@ First letter converted to upper case: \end{definition} (No case-change applied to PDF bookmarks.) +All caps: +\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 +First letter upper case: \begin{definition}[\DescribeMacro\Glsfmtfirstpl] \cs{Glsfmtfirstpl}\marg{label} \end{definition} +and all caps: +\begin{definition}[\DescribeMacro\GLSfmtfirstpl] +\cs{GLSfmtfirstpl}\marg{label} +\end{definition} \chapter{Categories} \label{sec:categories} @@ -7254,61 +7580,6 @@ overridden. \emph{This setting is incompatible with \catattr{aposplural}.} This 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. @@ -7408,6 +7679,10 @@ 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{glosssymbolfont}] (New to version 1.42.) +This is similar to \catattr{glossnamefont} and +\catattr{glossdescfont} but is used by \ics{glossentrysymbol}. + \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 @@ -7498,6 +7773,70 @@ external sources and doesn't require this attribute. \end{description} +If a term is defined using \ics{newabbreviation} and accessibility +support has been supplied via the \pkgopt{accsupp} package option +then the following attributes are also available. If +\gloskey{shortaccess} isn't set its value will be obtained from: +\begin{definition}[\DescribeMacro\glsdefaultshortaccess] +\cs{glsdefaultshortaccess}\marg{short}\marg{long} +\end{definition} +This is defined by \sty{glossaries-accsupp} to just do \meta{long} +but \sty{glossaries-extra} redefines it to do \meta{long} +(\meta{short}). The \catattr{accessinsertdots}, +\catattr{accessaposplural} and \catattr{accessnoshortplural} +attributes below refer to the \meta{short} form that's passed to +this command. + +The following attributes are only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}). They have no effect if the \pkgopt{accsupp} +package option hasn't been used. + +\begin{description} +\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 \meta{short} part used in the \gloskey{shortaccess} field instead +of the \gloskey{short} field. +This setting will be overridden by an explicit use of +the \gloskey{shortaccess} key in the optional argument +of \cs{newabbreviation} (or \cs{newacronym}). + +\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{nameshortaccess}] If this attribute is set to +\qt{true}, the \gloskey{access} field (used for the \gloskey{name} +field's accessibility support) automatically assigned if it's not +provided. + +\item[\catattrdef{textshortaccess}] Like \gloskey{nameshortaccess} +but applies to the \gloskey{textaccess} field automatically assigned if it's not +provided. + +\item[\catattrdef{firstshortaccess}] Like \gloskey{nameshortaccess} +but applies to the \gloskey{firstaccess} field automatically assigned if it's not +provided. + +\end{description} + An attribute can be set using: \begin{definition}[\DescribeMacro\glssetcategoryattribute] \cs{glssetcategoryattribute}\marg{category-label}\marg{attribute-label}\marg{value} @@ -8374,120 +8713,6 @@ Set the escape (quote) character to \meta{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} @@ -8922,6 +9147,11 @@ the associated glossary: \ics{printunsrtabbreviations}, \ics{printunsrtacronyms}, \ics{printunsrtsymbols}, \ics{printunsrtnumbers} and \ics{printunsrtindex}. +The \pkgopt{savenumberlist} package option doesn't have any effect +with \gls{bib2gls}. The location lists are saved by default, so +\sty{glossaries-extra-bib2gls} patches \ics{glsentrynumberlist} and +\ics{glsdisplaynumberlist} to work with the \gloskey{location} field + \begin{definition}[\DescribeMacro\glsxtrprovidecommand] \cs{glsxtrprovidecommand}\marg{cs}\oarg{n}\oarg{default}\marg{definition} \end{definition} @@ -10612,10 +10842,15 @@ 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} +If \sty{hyperref} is used, this uses \cs{texorpdfstring} and will expand to +\begin{definition}[\DescribeMacro\glsxtrpdfentryfmt] +\cs{glsxtrpdfentryfmt}\marg{label}\marg{text} +\end{definition} 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. +or just \meta{text} otherwise. The PDF bookmark version simply does +\meta{text}. It may be redefined, but remember that it needs to +expand fully. The \styfmt{glossaries} package provides \cs{glsaddstoragekey} to add new keys. This command will cause an error if the key has @@ -10801,6 +11036,30 @@ use: Again, version 1.39 introduced a starred form of these commands, which use the starred form of \cs{glsxtrifhasfield}. +As from v1.42, you can test if the field value is contained in a +comma-separated list with: +\begin{definition}[\DescribeMacro\GlsXtrIfFieldValueInCsvList] +\cs{GlsXtrIfFieldValueInCsvList}\marg{label}\marg{field}\marg{list}\marg{true}\marg{false} +\end{definition} +The unstarred version uses the unstarred form of +\cs{glsxtrifhasfield} (which adds grouping so \meta{true} and +\meta{false} will be localised). The starred version uses +\cs{glsxtrifhasfield*}. If the field value (without expansion) is +contained in \meta{list} then \meta{true} is done otherwise +\meta{false} is done. If the field hasn't been set \meta{false} is +done. This internally uses \cs{DTLifinlist} provided by +\sty{datatool-base} which performs a one level expansion on +\meta{list}. See the \sty{datatool} documentation for further +details. + +This command is intended for fields that contain a label. For +example, to test if the category is one of a set of labels: +\begin{verbatim} +\GlsXtrIfFieldValueInCsvList{examplelabel}{category}% + {abbreviation,acronym}% set of labels + {true part}{false part} +\end{verbatim} + 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} @@ -10883,7 +11142,36 @@ or \cs{glsxtrfieldforlistloop}\marg{label}\marg{field}\marg{handler} \end{definition} that internally use \cs{dolistcsloop} and \cs{forlistloop}, -respectively. +respectively. You can use \ics{listbreak} to break out of the loop +(see the \sty{etoolbox} manual for further details). + +For fields that contain comma-separated lists use +\cs{glsxtrforcsvfield} instead. + +New to v1.42: +\begin{definition}[\DescribeMacro\glsxtrfieldformatlist] +\cs{glsxtrfieldformatlist}\marg{label}\marg{field} +\end{definition} +Like \sty{datatool-base}'s \ics{DTLformatlist}, this iterates over +an (\sty{etoolbox}) internal list and formats each item. Uses all +the same helper commands as \cs{DTLformatlist} (the same list handler +macro is used). Unlike the \sty{datatool-base} command, this command +has no starred version. Grouping is automatically applied. + +For example, with \gls{bib2gls}['s] \texttt{save-child-count} +resource option: +\begin{verbatim} +\newcommand*{\listchildren}[1]{% + \GlsXtrIfFieldNonZero{childcount}{#1}% + {child count: \glscurrentfieldvalue; children: + \let\DTLlistformatitem\glsfmtname + \glsxtrfieldformatlist{#1}{childlist}% + }% + {no children}% +} +\end{verbatim} +For fields that contain a comma-separated list use \cs{glsxtrfieldformatcsvlist} +instead. There are also commands that use \cs{ifinlistcs}: \begin{definition}[\DescribeMacro\glsxtrfieldifinlist] @@ -10920,6 +11208,13 @@ which is just a synonym for \cs{@endfortrue}. The loop is performed within the true part of \cs{glsxtrifhasfield} so scoping is automatically applied. +New to v1.42: +\begin{definition}[\DescribeMacro\glsxtrfieldformatcsvlist] +\cs{glsxtrfieldformatcsvlist}\marg{label}\marg{field} +\end{definition} +Like \cs{glsxtrfieldformatcsvlist} but for fields that contain +comma-separated lists. + As from version 1.32, if the field given by \begin{definition}[\DescribeMacro\GlsXtrForeignTextField] \cs{GlsXtrForeignTextField} @@ -11572,6 +11867,120 @@ The value of the \gloskey{alias} field can be accessed using \cs{glsxtralias}\marg{label} \end{definition} +\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{Supplemental Packages} \label{sec:supplemental} @@ -11611,6 +12020,11 @@ Next use: \pgls{svm}. \section{Accessibility Support} \label{sec:accsupp} +\begin{important} +The \sty{glossaries-accsupp} package is still experimental and so +accessibility features are liable to change. +\end{important} + The \sty{glossaries-accsupp} package needs to be loaded before \styfmt{glossaries-extra} or through the \pkgopt{accsupp} package option: @@ -11621,7 +12035,9 @@ 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. +commands. Other accessibility features, such as the attributes used +by \ics{newabbreviation} also won't work if \sty{glossaries-accsupp} +is loaded too late. The following \cs{glsaccess}\meta{xxx} commands add accessibility information wrapped around the corresponding \cs{glsentry}\meta{xxx} commands. There is @@ -11978,7 +12394,7 @@ 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, +\texttt{glossariesxtr\dhyphen}\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 @@ -11991,9 +12407,9 @@ 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} +\texttt{glossariesxtr\dhyphen}\meta{lang}\texttt{.ldf}, where \meta{lang} identifies the language or dialect (see the \sty{tracklang} -package). For example, \texttt{glossariesxtr-french.ldf}. +package). For example, \nolinkurl{glossariesxtr-french.ldf}. The simplest code for this file is: \begin{verbatim} @@ -12107,8 +12523,6 @@ This produces the following text in English: \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} @@ -12117,7 +12531,9 @@ 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. + +See the documented code (\nolinkurl{glossaries-extra-code.pdf}) +for further details. \printglossaries \PrintIndex |