diff options
Diffstat (limited to 'macros/latex/contrib/glossaries/glossaries-user.tex')
| -rw-r--r-- | macros/latex/contrib/glossaries/glossaries-user.tex | 202 |
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} |