summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/glossaries/glossaries-user.tex')
-rw-r--r--macros/latex/contrib/glossaries/glossaries-user.tex202
1 files changed, 189 insertions, 13 deletions
diff --git a/macros/latex/contrib/glossaries/glossaries-user.tex b/macros/latex/contrib/glossaries/glossaries-user.tex
index 7b9fd3fe22..f8e0b48911 100644
--- a/macros/latex/contrib/glossaries/glossaries-user.tex
+++ b/macros/latex/contrib/glossaries/glossaries-user.tex
@@ -431,6 +431,9 @@ Predefined Styles}}
% example-glossaries-images.tex
\gfile{example\dhyphen glossaries\dhyphen images.tex}%
{\providedby{\sty{glossaries} v4.33+}}%
+ % example-glossaries-user.tex
+ \gfile{example\dhyphen glossaries\dhyphen user.tex}%
+ {\providedby{\sty{glossaries} v4.51+}}%
% example-glossaries-xr.tex
\gfile{example\dhyphen glossaries\dhyphen xr.tex}%
{\providedby{\sty{glossaries-extra} v1.16+}}%
@@ -1816,6 +1819,42 @@ Predefined Styles}}
\code{\meta{handler cs}\margm{element}} for each element of the
list}
}
+ % COMMANDS: UTILITIES - MEASURING
+ % \glsmeasureheight
+ \gcmd{gls\-measure\-height}
+ {
+ \providedby{\sty{glossaries} v4.51+}
+ \syntax{\margm{length}\margm{text}}
+ \desc{measures the height of \meta{text} using \gls{settoheight}
+ but temporarily switches off indexing, unset/reset and
+ labelling}
+ }
+ % \glsmeasuredepth
+ \gcmd{gls\-measure\-depth}
+ {
+ \providedby{\sty{glossaries} v4.51+}
+ \syntax{\margm{length}\margm{text}}
+ \desc{measures the depth of \meta{text} using \gls{settodepth}
+ but temporarily switches off indexing, unset/reset and
+ labelling}
+ }
+ % \glsmeasurewidth
+ \gcmd{gls\-measure\-width}
+ {
+ \providedby{\sty{glossaries} v4.51+}
+ \syntax{\margm{length}\margm{text}}
+ \desc{measures the width of \meta{text} using \gls{settowidth}
+ but temporarily switches off indexing, unset/reset and
+ labelling}
+ }
+ % \glsifmeasuring
+ \gcmd{gls\-if\-measuring}
+ {
+ \providedby{\sty{glossaries} v4.51+}
+ \syntax{\margm{true}\margm{false}}
+ \desc{does \meta{true} it it occurs inside a measuring content
+otherwise does \meta{false}}
+ }
% COMMANDS: ENTRY COUNTING
% \glsenableentrycount
\gcmd{gls\-enable\-entry\-count}
@@ -3538,6 +3577,33 @@ Predefined Styles}}
This command can't be used with \app{bib2gls}. Use the
\resourceoptval{selection}{all} \idx{resourceopt} instead}
}
+ % \glsaddeach
+ \gcmd{gls\-add\-each}
+ {
+ \providedby{\sty{glossaries-extra} v1.31+}
+ \syntax{\oargm{options}\margm{entry label list}}
+ \desc{does \code{\gls{glsadd}\oargm{options}\margm{entry-label}} for each label
+ in the supplied comma-separated list}
+ }
+ % \glsstartrange
+ \gcmd{gls\-start\-range}
+ {
+ \providedby{\sty{glossaries-extra} v1.50+}
+ \syntax{\oargm{options}\margm{entry label list}}
+ \desc{essentially does
+\code{\gls{glsaddeach}\oarg{\meta{options},\glsoptval{format}{\sym{startrange}\meta{encap}}}\margm{entry label
+list}}
+where \meta{encap} can either be provided by the \glsopt{format} key
+in \meta{options}}
+ }
+ % \glsendrange
+ \gcmd{gls\-end\-range}
+ {
+ \providedby{\sty{glossaries-extra} v1.50+}
+ \syntax{\oargm{options}\margm{entry label list}}
+ \desc{as \gls{glsstartrange} but with the end range marker
+ \sym{endrange}}
+ }
% \glssee
\gcmd{gls\-see}
{%
@@ -10677,6 +10743,9 @@ formats}
\gcmd{num\-ber\-line}{}% \numberline
\gcmd{add\-contents\-line}{}% \addcontentsline
\gcmd{en\-sure\-math}{}% \ensuremath
+ \gcmd{set\-to\-width}{}% \settowidth
+ \gcmd{set\-to\-height}{}% \settoheight
+ \gcmd{set\-to\-depth}{}% \settodepth
\gcmd{def}{}% \def
\gcmd{gdef}{}% \gdef
\gcmd{space}{\common}% \space
@@ -11412,11 +11481,11 @@ formats}
{\begin{information}[title={\app{bib2gls}}]}
{\end{information}}
-\title{User Manual for glossaries.sty v4.50}
+\title{User Manual for glossaries.sty v4.51}
\author{Nicola L.C. Talbot\\%
\href{http://www.dickimaw-books.com/contact}{\nolinkurl{dickimaw-books.com/contact}}}
-\date{2022-10-14}
+\date{2022-11-02}
\begin{document}
\maketitle
@@ -11500,7 +11569,7 @@ package.
\begin{itemdesc}
Advanced users wishing to know more about the inner workings of all the
packages provided in the \styfmt{glossaries} bundle should read
-\qt{Documented Code for glossaries v4.50}.
+\qt{Documented Code for glossaries v4.51}.
\end{itemdesc}
\itemtitle{\url{CHANGES}}
@@ -13512,6 +13581,44 @@ example:
\gloskeyval{description}{Quisque ullamcorper placerat ipsum.}}
\end{codebox}
+\filedef{example-glossaries-user.tex}
+The \toplevel\ entries have the \gloskey{symbol} key and all
+\gloskey{user1}, \glsaddeach{opt.gloskey.user2,opt.gloskey.user3,opt.gloskey.user4,opt.gloskey.user5}\ldots, \gloskey{user6} keys set. For example:
+\begin{codebox}
+\gls{newglossaryentry}\marg{sample-a}
+\marg{\gloskeyval{name}{a name},
+\gloskeyval{description}{a description},
+\gloskeyval{symbol}{\cmd{ensuremath}\marg{\cmd{alpha}}},
+\gloskeyval{user1}{A},
+\gloskeyval{user2}{1},
+\gloskeyval{user3}{i},
+\gloskeyval{user4}{A-i},
+\gloskeyval{user5}{25.2020788573521},
+\gloskeyval{user6}{1585-11-06}}
+\end{codebox}
+There are also some \hierlevel{1} entries, which may or may not have
+the \gloskey{symbol} and user keys set. For example:
+\begin{codebox}
+\gls{newglossaryentry}\marg{sample-b-0}
+\marg{\gloskeyval{parent}{sample-b},
+\gloskeyval{name}{b/0 name},
+\gloskeyval{description}{child 0 of b},
+\gloskeyval{symbol}{\cmd{ensuremath}\marg{\cmd{sigma}}},
+\gloskeyval{user2}{0},
+\gloskeyval{user4}{a-i}}
+\end{codebox}
+There are no deeper \hierarchical\ entries. Where set, the
+\gloskey{user1} key is an \idx{uppercase} letter (A--Z), the
+\gloskey{user2} key is an integer, the \gloskey{user3} key is a
+\idx{lowercase} Roman numeral, the \gloskey{user4} key is in the
+form \meta{alpha}-\meta{roman} where \meta{alpha} is either an
+upper or \idx{lowercase} letter (a--z or A--Z) and \meta{roman} is
+either an upper or \idx{lowercase} Roman numeral. The
+\gloskey{user5} key is a random number (in the range $(-50,+50)$
+for \toplevel\ entries and $(-1,+1)$ for child entries).
+The \gloskey{user6} key is a random date between 1000-01-01 and
+2099-12-31.
+
\filedef{example-glossaries-images.tex}
These entries use the \gloskey{user1} key to store the name of an
image file. (The images are provided by the \sty{mwe} package and
@@ -14499,7 +14606,7 @@ Perl. There's more information about this at
\begin{important}
When upgrading the \sty{glossaries} package, make sure you also
upgrade your version of \app{makeglossaries}. The current version is
-4.50.
+4.51.
\end{important}
Some of the options are only applicable to \app{makeindex} and some
@@ -15947,7 +16054,7 @@ this will also load \styfmt{glossary-\meta{element}.sty} for each
\section{Indexing Options}
\label{sec:pkgopts-indexing}
-\glsadd[format=(]{indexing}%
+\glsstartrange{indexing}%
\optiondef{seenoindex}
(This option is only relevant with \app{makeindex} and \app{xindy}.)
The \gloskey{see} key automatically \idxc{indexing}{indexes} the
@@ -16173,7 +16280,7 @@ This valueless option is primarily intended for use with
(rather than the top of the page). Unexpected results will occur
with other indexing methods. See \sty{glossaries-extra} manual for
further details.
-\glsadd[format=)]{indexing}%
+\glsendrange{indexing}%
\section{Sorting Options}
\label{sec:pkgopts-sort}
@@ -19374,12 +19481,11 @@ query and state change. This includes frames with overlays in
\cls{beamer} and the \env{tabularx} environment provided by \sty{tabularx}.
The \sty{glossaries} package automatically deals with this issue
in \sty{amsmath}'s \env{align} environment. You can apply a patch
-to \sty{tabularx} by placing the following command in the
-\idx{documentpreamble}:
-\cmddef{glspatchtabularx}
+to \sty{tabularx} by placing the command \gls{glspatchtabularx} in the
+\idx{documentpreamble}.
This does nothing if \sty{tabularx} hasn't been loaded. There's no
patch available for \cls{beamer}. See \sectionref{sec:glsunset} for
-more details.
+more details and also \sectionref{sec:measuring}.
Most of the commands below have \casechanging\ variants to convert
the \idx+{linktext} to \idx+{sentencecase} or \idx+{allcaps}. The
@@ -23315,6 +23421,12 @@ Lots of text about sets spanning page 3 to page 8.
See \sectionref{sec:encap} for more information about the
\idx{locationencap}.
+\begin{xtr}
+Explicit ranges can also be created using \gls{glsstartrange}
+and \gls{glsendrange} with \sty{glossaries-extra}. You can also add
+a subset of entries with \gls{glsaddeach}.
+\end{xtr}
+
To add all entries that have been defined, use:
\cmddef{glsaddall}
The optional argument is the same as for \gls{glsadd}, except
@@ -23333,6 +23445,7 @@ do:
If you are using \app{bib2gls} with \sty{glossaries-extra}, you
can't use \gls{glsaddall}. Instead use the \resourceoptval{selection}{all}
resource option to select all \idxpl{entry} in the given \ext+{bib} files.
+(You can use \gls{glsaddeach} with \app{bib2gls}.)
\end{bib2gls}
\begin{important}
@@ -23387,10 +23500,14 @@ you intend to use have already been used and make sure to use the
\end{important}
\begin{bib2gls}
-Since \app{bib2gls} was designed specifically for
+You can't use \gls{glsaddallunused} with \app{bib2gls}. However,
+since \app{bib2gls} was designed specifically for
\sty{glossaries-extra}, it recognises \encap{glsignore} as a special
format that indicates the \location\ shouldn't be added to the
\idx{locationlist} but the \idx{entry} should be selected.
+So you can index an entry with \glsoptval{format}{\encap{glsignore}}
+to ensure that the entry is selected without adding a \location\ to
+the \idx{numberlist}.
Alternatively, the \resourceoptval{selection}{all} resource option
can be used, which will ensure all \idxpl{entry} are selected but only
@@ -24116,6 +24233,12 @@ to close the \idx{range}. This will create an explicit \idx{range} in the
\encap{glsnumberformat} should be used, you can omit it and just
have the \sym{startrange} and \sym{endrange} characters.
+\begin{xtr}
+Explicit ranges can also be created using \gls{glsstartrange}
+and \gls{glsendrange} with \sty{glossaries-extra}.
+\end{xtr}
+
+
Implicit \idxpl{range} are formed by concatenating a sequence of
three or more consecutive \locations. For example, if an \idx{entry}
is \indexed\ on pages~3, 4, 5, and 6, this will be compacted into
@@ -27115,7 +27238,7 @@ but also units (stored in \gloskey{user1}) and dimension
\chapter{Xindy (Option \glsfmttext{idx.opt.xdy})}
\label{sec:xindy}
-\glsaddeach[format=(]{app.xindy,ext.xdy}%
+\glsstartrange{app.xindy,ext.xdy}%
If you want to use \app{xindy} to sort the \idx{glossary}, you
must use the package option \opt+{xindy}:
\begin{codebox}
@@ -27766,7 +27889,7 @@ Note that these commands have no effect if
\gls{makeglossaries}.
\end{important}
-\glsaddeach[format=)]{app.xindy,ext.xdy}
+\glsendrange{app.xindy,ext.xdy}
\chapter{Utilities}
\label{sec:utilities}
@@ -28319,6 +28442,59 @@ This robust command is like {ifglsfielddefeq}
but internally uses \sty{etoolbox}'s \gls{ifcsstrequal} command
instead of \gls{ifdefstrequal}.
+\section{Measuring}
+\label{sec:measuring}
+
+Sometimes it's necessary to measure the width or height of some
+text. For example, \gls{glsdohypertarget} measures the height of the
+supplied text to position the target at the top of the line instead
+of at the baseline (where it can cause the line to scroll up out of
+view). Some styles measure the width of text to assist with
+alignment.
+
+Measuring can be performed using \gls{settowidth}, \gls{settoheight}
+and \gls{settodepth}, but if the content being measured contains any
+\idx{glslike} or \idx{glstextlike} commands, or if it contains
+commands like \gls{glsentryitem}, it can cause duplication. (See
+also \sectionref{sec:glsunset} for the problems this can cause with
+unsetting and resetting the \idx{firstuseflag}.)
+
+The following measuring commands locally disable \idx{indexing}, the
+unset/reset commands, and \gls{label}, and adjust
+\gls{refstepcounter} to only locally update the counter value.
+
+\cmddef{glsmeasureheight}
+Measures the height of \meta{text} and stores the result in the
+supplied \meta{length} register.
+
+\cmddef{glsmeasuredepth}
+Measures the depth of \meta{text} and stores the result in the
+supplied \meta{length} register.
+
+\cmddef{glsmeasurewidth}
+Measures the width of \meta{text} and stores the result in the
+supplied \meta{length} register.
+
+You can test if content is inside an area that's being measured
+with:
+\cmddef{glsifmeasuring}
+This will do \meta{true} if it occurs inside either of the above
+commands and does \meta{false} otherwise. This will also take
+\sty{amsmath}['s] \cmd{ifmeasuring@} into account.
+
+If \sty{tabularx} is loaded, its \cmd{TX@trial} command can be
+patched with:
+\cmddef{glspatchtabularx}
+If you use \sty{tabularx} and have any of the \idx{glslike} commands
+inside a \env{tabularx} environment, you will need to use
+\gls{glspatchtabularx} in the \idx{documentpreamble} to disable
+unset/reset while the environment measures its content.
+
+\begin{warning}
+Patches made on other package's internal commands may break if the
+other package removes those commands or changes their definitions.
+\end{warning}
+
\section{Fetching and Updating the Value of a Field}
\label{sec:fetchset}