diff options
Diffstat (limited to 'macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r-- | macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex | 277 |
1 files changed, 210 insertions, 67 deletions
diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex index 1bedd53c53..ad6d582b3b 100644 --- a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex +++ b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex @@ -10249,6 +10249,86 @@ but not \printglossopt{leveloffset})} \desc{like \gls{GlsXtrIfFieldEqStr} but first (protected) expands both the field value and the supplied \meta{value}} } + % \glossaries_if_field_exists_p:nn + % \glossaries_if_field_exists:nnT + % \glossaries_if_field_exists:nnF + % \glossaries_if_field_exists:nnTF + \gexplpred{glossaries\dsb if\dsb field\dsb exists}{nn} + { + \providedby{\sty{glossaries-extra} v1.55+} + \syntax{\ \margm{entry-label} \margm{field-label} \TFsyntax} + \desc{true if the entry identified by \meta{entry-label} exists and has an +\idxc{internalfieldlabel}{internal field} identified by \meta{field-label} (which may or may not be empty)} + } + % \glossaries_if_field_set_p:nn + % \glossaries_if_field_set:nnT + % \glossaries_if_field_set:nnF + % \glossaries_if_field_set:nnTF + \gexplpred{glossaries\dsb if\dsb field\dsb set}{nn} + { + \providedby{\sty{glossaries-extra} v1.55+} + \syntax{\ \margm{entry-label} \margm{field-label} \TFsyntax} + \desc{true if the entry identified by \meta{entry-label} exists and has an +\idxc{internalfieldlabel}{internal field} identified by \meta{field-label} set to a value +that is not empty and not \gls{relax}} + } + % \glossaries_if_field_eq_p:nnN + % \glossaries_if_field_eq:nnTN + % \glossaries_if_field_eq:nnFN + % \glossaries_if_field_eq:nnTFN + \gexplpred{glossaries\dsb if\dsb field\dsb eq}{nnN} + { + \providedby{\sty{glossaries-extra} v1.55+} + \syntax{\ \margm{entry-label} \margm{field-label} \meta{value-tl-var} \TFsyntax} + \desc{true if the entry identified by \meta{entry-label} exists and has an +\idxc{internalfieldlabel}{internal field} identified by \meta{field-label} that +has the same value as the given token list variable} + } + % \glossaries_if_field_eq:nnnT + % \glossaries_if_field_eq:nnnF + % \glossaries_if_field_eq:nnnTF + \gexplcond{glossaries\dsb if\dsb field\dsb eq}{nnn} + { + \providedby{\sty{glossaries-extra} v1.55+} + \syntax{\ \margm{entry-label} \margm{field-label} \margm{value-tl} \TFsyntax} + \desc{true if the entry identified by \meta{entry-label} exists and has an +\idxc{internalfieldlabel}{internal field} identified by \meta{field-label} that +has the given value} + } + % \glossaries_if_field_eq_field_p:nnnN + % \glossaries_if_field_eq_field:nnnTN + % \glossaries_if_field_eq_field:nnnFN + % \glossaries_if_field_eq_field:nnnTFN + \gexplpred{glossaries\dsb if\dsb field\dsb eq\dsb field}{nnn} + { + \providedby{\sty{glossaries-extra} v1.55+} + \syntax{\ \margm{entry-label} \margm{field-label} \meta{field2-label} \TFsyntax} + \desc{true if the entry identified by \meta{entry-label} exists and has an +\idxc{internalfieldlabel}{internal field} identified by \meta{field-label} that +has the same value as the second field identified by \meta{field2-label} +(for the same entry)} + } + % \glossaries_if_field_eq_field_p:nnnnN + % \glossaries_if_field_eq_field:nnnnTN + % \glossaries_if_field_eq_field:nnnnFN + % \glossaries_if_field_eq_field:nnnnTFN + \gexplpred{glossaries\dsb if\dsb field\dsb eq\dsb field}{nnnn} + { + \providedby{\sty{glossaries-extra} v1.55+} + \syntax{\ \margm{entry-label} \margm{field-label} \margm{entry2-label} \meta{field2-label} \TFsyntax} + \desc{true if the entry identified by \meta{entry-label} exists and has an internal field +identified by \meta{field-label} +and the entry identified by \meta{entry2-label} exists and has an internal field +identified by \meta{field2-label} and both field values are the same} + } + % \glossaries_use_field:nn + \gcmd{glossaries\dsb use\dsb field:nn} + { + \providedby{\sty{glossaries-extra} v1.55+} + \syntax{\ \margm{entry-label} \margm{field-label}} + \desc{expands to the value of the field identified by its \idx{internalfieldlabel} +for the entry identifed by \meta{entry-label} (produces an error if either the field or entry are undefined)} + } % \glsxtrforcsvfield \gcmds{gls\-xtr\-for\-csv\-field} { @@ -17632,7 +17712,7 @@ commands} \providedby{\sty{glossaries-extra} v1.49+} \syntax{\margm{options}} \desc{overrides the options that should be implemented by the - star (\code{*}) modifier for \idx{glslike} and + star (\cmdmod{star}) modifier for \idx{glslike} and \idx{glstextlike} commands} } % \GlsXtrSetPlusModifier @@ -17641,7 +17721,7 @@ commands} \providedby{\sty{glossaries-extra} v1.49+} \syntax{\margm{options}} \desc{overrides the options that should be implemented by the - plus (\code{+}) modifier for \idx{glslike} and + plus (\cmdmod{plus}) modifier for \idx{glslike} and \idx{glstextlike} commands} } % \glslinkwrcontent @@ -18519,13 +18599,24 @@ command line switches)} % \glsxtrresourcefile \gcmd{gls\-xtr\-re\-source\-file}% {% + \deprecated \providedby{\sty{glossaries-extra} v1.11+} \syntax{\oargm{options}\margm{basename}} \field{seealso}{idx.resourceopt,GlsXtrLoadResources} \desc{for use with \app{bib2gls}, this both sets up the options for the \idx{resourceset} (which \app{bib2gls} can detect from the \ext{aux} file) and inputs the file \metafilefmt{}{basename}{.glstex} file - created by \app{bib2gls}} + created by \app{bib2gls}. This command is now deprecated. Use + \gls{glsbibdata} instead} + } + % \glsbibdata + \gcmd{gls\-bib\-data}% + {% + \providedby{\sty{glossaries-extra} v1.55+} + \syntax{\oargm{options}\margm{bib-list}} + \field{seealso}{idx.resourceopt,GlsXtrLoadResources} + \desc{shortcut that uses \gls{GlsXtrLoadResources} with + \resourceopt{src} set to \meta{bib-list}} } % \GlsXtrLoadResources \gcmd{Gls\-Xtr\-Load\-Re\-sources}% @@ -18533,8 +18624,10 @@ command line switches)} \providedby{\sty{glossaries-extra} v1.11+} \syntax{\oargm{options}} \field{seealso}{idx.resourceopt} - \desc{a shortcut that uses - \gls{glsxtrresourcefile}\oargm{options}\margm{basename}, where + \desc{for use with \app{bib2gls}, this both sets up the options + for the \idx{resourceset} (which \app{bib2gls} can detect from the + \ext{aux} file) and inputs the file \metafilefmt{}{basename}{.glstex} + created by \app{bib2gls} (if it exists), where the \meta{basename} is obtained from \gls{jobname} and \gls{glsxtrresourcecount}} } @@ -18552,7 +18645,7 @@ command line switches)} \providedby{\sty{glossaries-extra} v1.21+} \desc{may be defined to temporarily change command definitions before information is written to the \ext{aux} file by the protected - write used by \gls{glsxtrresourcefile}} + write used by \gls{GlsXtrLoadResources}} \field{seealso}{GlsXtrResourceInitEscSequences} } % \GlsXtrResourceInitEscSequences @@ -18599,7 +18692,7 @@ command line switches)} \gcmd{gls\-xtr\-MFU\-save} { \providedby{\sty{glossaries-extra} v1.49+} - \desc{used on the first instance of \gls{glsxtrresourcefile}, + \desc{used on the first instance of \gls{GlsXtrLoadResources}, this will add \gls{MFUsave} to the begin document hook and then disable itself. This is provided to help \app{bib2gls} pick up any of \sty{mfirstuc}['s] exclusions, blockers and @@ -20111,7 +20204,7 @@ command line switches)} \gidx{resourceopt}{\name{resource options}% \field{text}{resource option}% \desc{these options may be used in the optional argument of - \gls{GlsXtrLoadResources} and \gls{glsxtrresourcefile}} + \gls{GlsXtrLoadResources} and \gls{glsbibdata}} } % resource option loc-prefix \gresourceopt{loc\dhyphen prefix}% @@ -20166,6 +20259,14 @@ command line switches)} \initval{recorded and deps and see} \desc{the selection criteria} } + % resource option master + \gresourceopt{master}% + {% + \syntax{\meta{basename}} + \desc{indicates that the resources identified in the given + \metafilefmt{}{basename}{.aux} file (from another document) + should be used} + } % resource option copy-to-glossary \gresourceopt{copy\dhyphen to\dhyphen glossary}% {% @@ -21892,13 +21993,13 @@ according to the given \meta{setting}} {% \name{resource set} \desc{all the settings (\idxpl{resourceopt}) and entries associated with a particular - instance of \gls{GlsXtrLoadResources} (or \gls{glsxtrresourcefile})} + instance of \gls{GlsXtrLoadResources} (or \gls{glsbibdata})} } \gterm{resourcefile}% {% \name{resource file} \desc{the \ext+{glstex} file created by \app{bib2gls} and loaded by - \gls{GlsXtrLoadResources} (or \gls{glsxtrresourcefile})} + \gls{GlsXtrLoadResources} (or \gls{glsbibdata})} } \gterm{field}% {% @@ -22054,13 +22155,13 @@ according to the given \meta{setting}} } } -\title{\styfmt{glossaries-extra.sty} v1.54: +\title{\styfmt{glossaries-extra.sty} v1.55: an extension to the \styfmt{glossaries} package} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \href{https://www.dickimaw-books.com/}{\nolinkurl{dickimaw-books.com}}} -\date{2025-01-03 +\date{2025-01-29 } \begin{document} \maketitle @@ -23136,7 +23237,7 @@ This setting indicates whether or not \app{bib2gls} is required. \begin{information} This option can only be set in the preamble and can't be used after -\gls{GlsXtrLoadResources} or \gls{glsxtrresourcefile}. +\gls{GlsXtrLoadResources} or \gls{glsbibdata}. \end{information} With the \opt{record} setting on (that is, any value other than @@ -23163,7 +23264,7 @@ This setting implements \opteqvalref{undefaction}{error}. \Glsname{dual.indexing} is performed by adding \app{bib2gls} \records\ in the \ext{aux} file. Neither \gls{makeglossaries} nor \gls{makenoidxglossaries} is permitted. -Use \gls{GlsXtrLoadResources} (or \gls{glsxtrresourcefile}) +Use \gls{GlsXtrLoadResources} (or \gls{glsbibdata}) to set up \app{bib2gls} \idxpl{resourceopt}. Glossaries should be displayed with the \idx{unsrtfam}, such as \gls{printunsrtglossary}. @@ -28182,14 +28283,14 @@ the corresponding field value (possibly encapsulated with \gls{glstext} or the final argument of \gls{glslink}. The \idx{glslike} and \idx{glstextlike} commands can all be used -with a star (\code{*}) or plus (\code{+}) modifier. The star +with a star (\cmdmod+{star}) or plus (\cmdmod+{plus}) modifier. The star modifier automatically implements \glsoptval{hyper}{false} (disables the hyperlink) and the plus modifier automatically implements \glsoptval{hyper}{true} (forces the hyperlink on, if supported). With \sty{glossaries-extra}, it's possible to define an additional -modifier for your own use with: +modifier (\cmdmod+{alt-mod}) for your own use with: \cmddef{GlsXtrSetAltModifier} The \meta{token} must be a single token, so a multi-byte \idx{utf8} character will required a native Unicode engine (\XeLaTeX\ or \LuaLaTeX). @@ -31809,8 +31910,8 @@ command that automatically adds the prefix. For example, \cmd{newcommand}*\marg{\cmd{cs}}[2][]\marg{\gls{gls}\oarg{\#1}\marg{cs.\#2}} \end{codebox} The problem with this is that the custom command \csfmt{cs} -doesn't allow for the \cmdmod{star}, \cmdmod{plus} and -\cmdmod{alt-mod} modifiers (such as \code{\gls{gls}*} or \code{\gls{gls}+}). +doesn't allow for the \cmdmod+{star}, \cmdmod+{plus} and +\cmdmod+{alt-mod} modifiers (such as \code{\gls{gls}*} or \code{\gls{gls}+}). Instead you can use: \cmddef{glsxtrnewgls} which defines the command @@ -34462,6 +34563,52 @@ This is like \gls{GlsXtrIfFieldEqStr} but expands both the field value and the string before the comparison. This also has an starred version that doesn't add implicit grouping. +There are additional conditionals described in the next section. + +\section{\LaTeX3 Commands} +\label{sec:latex3utilities} + +These commands all require \LaTeX3 syntax to be on. Unlike most of the +commands in the previous section, there is no grouping or starred version and +no assignment of \gls{glscurrentfieldvalue}. In all cases, the \idx{field} +is identified by its \idxc{internalfieldlabel}{internal label}. The test for +existence means testing if the field exists for the given entry. Existence +doesn't automatically mean that there's a corresponding key. + +\cmddef{glossariesiffieldexists:nn} +True if the entry identified by \meta{entry-label} exists and has an internal field +identified by \meta{field-label} (which may or may not be empty). + +\cmddef{glossariesiffieldset:nn} +True if the entry identified by \meta{entry-label} exists and has an +internal field identified by \meta{field-label} set to a value +that is not empty and not \gls{relax}. + +\cmddef{glossariesiffieldeq:nnN} +True if the entry identified by \meta{entry-label} exists and has an internal field +identified by \meta{field-label} that has the same value as the given token list +variable. + +\cmddef{glossariesiffieldeq:nnn} +True if the entry identified by \meta{entry-label} exists and has an internal field +identified by \meta{field-label} that has the given value. + +\cmddef{glossariesiffieldeqfield:nnn} +True if the entry identified by \meta{entry-label} exists and has an internal field +identified by \meta{field-label} that has the same value as the internal field +identified by \meta{field2-label} (for the same entry). + +\cmddef{glossariesiffieldeqfield:nnnn} +True if the entry identified by \meta{entry-label} exists and has an internal field +identified by \meta{field-label} +and the entry identified by \meta{entry2-label} exists and has an internal field +identified by \meta{field2-label} and both field values are the same. + +\cmddef{glossariesusefield:nn} +Expands to the value of the field identified by its \idx{internalfieldlabel} +\meta{field-label} for the entry identifed by \meta{entry-label}. An error will +occur if either the field or entry are undefined). + \chapter{Counting References} \label{sec:countref} @@ -44143,11 +44290,11 @@ that has a corresponding \longargfmt{no-\meta{switch}} becomes a boolean option. For example: \begin{codebox} -\gls{BibGlsOptions}\marg{\bibglsswitchopt{group},\bibglsswitchoptfalse{collapse-same-locations}} +\gls{BibGlsOptions}\marg{\bibglsswitchopt{group},\bibglsswitchoptfalse{collapse-same-location-range}} \end{codebox} is equivalent to: \begin{terminal} -bib2gls \switch{group} \longargfmt{no-collapse-same-locations} \meta{filename} +bib2gls \switch{group} \longargfmt{no-collapse-same-location-range} \meta{filename} \end{terminal} This will require at least version 4.0 of \app{bib2gls}. From the point of view of \sty{glossaries-extra}, the \gls{BibGlsOptions} @@ -44181,50 +44328,45 @@ If you are using \sty{hyperref}, you may prefer to use \opteqvalref{record}{nameref}. The \ext{glstex} file created by \app{bib2gls} is loaded using: -\cmddef{glsxtrresourcefile} -where \meta{basename} is the basename (without the extension) of the -\ext{glstex} file. This command will redefine \gls{glsindexingsetting} -to \code{bib2gls} (or \code{bib2gls-xindy} or -\code{bib2gls-makeindex} if \opteqvalref{record}{hybrid}). -There's a shortcut version: \cmddef{GlsXtrLoadResources} -This internally uses \gls{glsxtrresourcefile} and sets the -\meta{basename} to \gls{jobname} in the first instance and to +This both sets up the options for the \idx{resourceset} (which \app{bib2gls} +can detect from the \ext{aux} file) and inputs the file +\metafilefmt{}{basename}{.glstex} created by \app{bib2gls} (if it exists), +where the \meta{basename} is \gls{jobname} in the first instance and \code{\gls{jobname}-\meta{n}} on subsequent instances (where \meta{n} is incremented at the end of every \gls{GlsXtrLoadResources}). -For example: -\begin{codebox} -\cmd{usepackage}\oarg{record}\marg{glossaries-extra} -\gls{GlsXtrLoadResources}\oarg{\resourceoptvalm{src}{terms,moreterms}} -\gls{GlsXtrLoadResources}\oarg{\resourceoptvalm{src}{symbols,constants}} -\gls{GlsXtrLoadResources}\oarg{\resourceoptvalm{src}{abbreviations}} -\end{codebox} -is equivalent to: -\begin{codebox}[before upper app=\small] -\cmd{usepackage}\oarg{record}\marg{glossaries-extra} -\gls{glsxtrresourcefile}\oarg{\resourceoptvalm{src}{terms,moreterms}}\marg{\gls{jobname}} -\gls{glsxtrresourcefile}\oarg{\resourceoptvalm{src}{symbols,constants}}\marg{\gls{jobname}-1} -\gls{glsxtrresourcefile}\oarg{\resourceoptvalm{src}{abbreviations}}\marg{\gls{jobname}-2} -\end{codebox} +If the optional argument is missing, \app{bib2gls} will assume the +option \resourceoptval{src}{\meta{basename}}. In general, you will need to +supply \resourceopt{src}, particularly if you have multiple \idxpl{resourceset}. + +\begin{information} +\gls{GlsXtrLoadResources} will redefine \gls{glsindexingsetting} +to \code{bib2gls} (or \code{bib2gls-xindy} or \code{bib2gls-makeindex} if +\opteqvalref{record}{hybrid}). +\end{information} + +There is a shortcut command: +\cmddef{glsbibdata} +This simply does: +\begin{compactcodebox} +\gls{GlsXtrLoadResources}\oarg{\resourceoptvalm{src}{\meta{bib-list}},\meta{options}} +\end{compactcodebox} + If required, the value of \meta{n} is stored in the count register: \cmddef{glsxtrresourcecount} although there should be little need to use this. \begin{information} -Since \gls{GlsXtrLoadResources} is more convenient to use than -\gls{glsxtrresourcefile}, all examples use -\gls{GlsXtrLoadResources}. +Note that \gls{glsxtrresourcefile} is now deprecated. Use \gls{glsbibdata} +instead. (Remember that if you want to share a \idx{resourceset}, including +locations, across multiple documents, you need to use the \resourceopt{master} +resource option.) \end{information} -The \gls{glsxtrresourcefile} command writes the following to +The \gls{GlsXtrLoadResources} command writes the following to the \ext{aux} file: \cmddef{glsxtr@resource} -and will input \metafilefmt{}{filename}{.glstex} if it exists. -(Version 1.08 assumed \metafilefmt{}{filename}{.tex} but that's -potentially dangerous if, for example, \meta{filename} happens to be -the same as \gls{jobname}. The \ext+{glstex} extension was enforced -by version 1.11.) - +This command is searched for by \gls{bib2gls}. If you are using or developing a build system that needs to know which applications to run as part of the document build, you can search the \ext{aux} for instances of \gls{glsxtr@resource}. For @@ -44239,16 +44381,17 @@ File Commands Provided by \styfmt{glossaries.sty} and Since the \ext{glstex} file won't exist on the first \LaTeX\ run, the \opt{record} package option additionally switches on \opteqvalref{undefaction}{warn}. Any use of commands like \gls{gls} or -\gls{glstext} will produce \idx{unknowntag} in the document, since the entries are -undefined at this point. Once \app{bib2gls} has created the -\ext{glstex} file the references should be resolved. -This may cause a shift in the locations if the actual text produced -once the entry is defined is significantly larger than the -placeholder \idx{unknowntag} (as this can alter the page breaking). - -Note that as from v1.12, \gls{glsxtrresourcefile} temporarily +\gls{glstext} will produce \idx{unknowntag} in the document, since the entries +are undefined at this point. Once \app{bib2gls} has created the \ext{glstex} +file the references should be resolved. This may cause a shift in the +locations if the actual text produced once the entry is defined is +significantly larger than the placeholder \idx{unknowntag} (as this can alter +the page breaking). + +Note that as from v1.12, \gls{GlsXtrLoadResources} temporarily switches the category code of \code{@} to 11 (letter) while it -reads the file to allow for any internal commands. +reads the file to allow for any internal commands. Be aware of this if +you have any entry fields that include the \code{@} character. \begin{information} The package options \opteqvalref{record}{only} and @@ -44259,8 +44402,8 @@ that are useful with \app{bib2gls}. Since they cover sorting and \opteqvalref{record}{hybrid} option. \end{information} -The information provided in the arguments of \gls{glsxtrresourcefile} -(and therefore also with \gls{GlsXtrLoadResources}) +The information provided in the optional argument of \gls{GlsXtrLoadResources} +(and therefore also with \gls{glsbibdata}) is written to the \ext{aux} file using: \begin{compactcodebox} \cmd{protected@write}\cmd{@auxout}\marg{\gls{glsxtrresourceinit}}\margm{information} @@ -44286,7 +44429,7 @@ it more convenient to redefine \gls{glsxtrresourceinit} to use \cmddef{glsxtrMFUsave} If you have \sty{mfirstuc} v2.08+, \gls{glsxtrMFUsave} will be used on the -first instance of \gls{glsxtrresourcefile}, and will add +first instance of \gls{GlsXtrLoadResources}, and will add \gls{MFUsave} to the begin document hook and then disable itself. This is provided to help \app{bib2gls} v3.0+ pick up any of \sty{mfirstuc}['s] exclusions, blockers and mappings to assist with @@ -44294,8 +44437,8 @@ its \idx{sentencecase} function. The assumption is that all exclusions, blockers and mappings will be set up in the preamble. If there are any within the \env{document} environment that you want \app{bib2gls} to be aware of, redefine this command to do nothing -before the first instance of \gls{glsxtrresourcefile} (or -\gls{GlsXtrLoadResources}) and use \gls{MFUsaveatend} instead. +before the first instance of \gls{GlsXtrLoadResources} (or +\gls{glsbibdata}) and use \gls{MFUsaveatend} instead. If the expansion text is non-empty for the command: \cmddef{GlsXtrDefaultResourceOptions} @@ -44759,7 +44902,7 @@ arara={pdflatex,bib2gls,pdflatex,pdfcrop} \codepar \gls{BibGlsOptions}\marg{mfirstuc-protection=\marg{long}} \codepar -\gls{setabbreviationstyle}\marg{long-short-sc} +\gls{setabbreviationstyle}\marg{long-short-sc}\nl \cmd{newcommand}\marg{\gls{BibGlsNoCaseChange}}[1]\marg{\gls{textsmaller}\marg{\#1}} \codepar \gls{GlsXtrLoadResources}\oarg{\nlsp |