diff options
author | Karl Berry <karl@freefriends.org> | 2017-02-05 23:22:17 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-02-05 23:22:17 +0000 |
commit | 17efbb93c3c280ebec43438b10c53601758ef11e (patch) | |
tree | a113323608fcf1d4538b75835d3d28b8b6bae6be /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex | |
parent | 9cb0c9d7ad125c5b287bfc285ebf1bf94749494a (diff) |
glossaries-extra (4feb17)
git-svn-id: svn://tug.org/texlive/trunk@43152 c570f23f-e606-0410-a88d-b1316a301751
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 | 1224 |
1 files changed, 1100 insertions, 124 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 b531dedd609..78dd9913911 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 @@ -71,6 +71,17 @@ called \texttt{makeglossaries-lite} (without the \texttt{.lua} extension) to the actual \texttt{makeglossaries-lite.lua} script.} } +\newglossaryentry{bib2gls}{% +name={\appfmt{bib2gls}\index{bib2gls=\appfmt{bib2gls}|htextbf}},% +sort={bib2gls},% +text={\appfmt{bib2gls}\iapp{bib2gls}},% +description={A command line Java application that selects +entries from a .bib file and converts them to glossary +definitions. At the time of writing, this application +is still under development. Further details at: +\url{https://github.com/nlct/bib2gls}.}% +} + \newglossaryentry{numberlist}{% name={number list},% description={A list of \glspl{entrylocation} (also @@ -155,13 +166,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}} \DeleteShortVerb{\|} \MakeShortVerb{"} - \title{glossaries-extra.sty v1.11: + \title{glossaries-extra.sty v1.12: an extension to the glossaries package} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} - \date{2017-01-19} + \date{2017-02-03} \maketitle \begin{abstract} @@ -477,14 +488,12 @@ over a glossary list. This includes \ics{forglsentries} and \ics{glsaddall}. \end{important} -\item[{\pkgopt{record}}] (New to v1.08.) This is a \meta{key}=\meta{value} +\item[{\pkgopt{record}}]\label{opt:record}(New to v1.08.) This is a \meta{key}=\meta{value} option, which has three allowed values: \pkgoptfmt{off} (default), \pkgoptfmt{only} and \pkgoptfmt{alsoindex}. If the value is omitted \pkgoptfmt{only} is assumed. The option is provided for the benefit -of any post-processing applications that need to know information -about the entries used in the document, such as -\href{https://github.com/nlct/bib2gls}{bib2gls}.\footnote{Still -under development at the time of writing this.} +of \gls{bib2gls} (see \sectionref{sec:bib2gls}). + The option may only be set in the preamble. The \pkgopt[off]{record} option switches off the recording, as per @@ -499,94 +508,11 @@ or \cs{makenoidxglossaries} has been used) whereas With the recording on, any of the commands that would typically index the entry (such as \cs{gls}, \cs{glstext} or \cs{glsadd}) will add a \cs{glsxtr@record} entry to the \texttt{.aux} file. -The post-processing application can then read these lines to find +\gls{bib2gls} can then read these lines to find out which entries have been used. (Remember that commands like \cs{glsentryname} don't index, so any use of these commands won't add a corresponding \cs{glsxtr@record} entry to the \texttt{.aux} -file.) - -There are new commands that are intended for use with the -recording function: -\begin{definition}[\DescribeMacro\glsxtrresourcefile] -\cs{glsxtrresourcefile}\oarg{options}\marg{filename} -\end{definition} -(Don't include the file extension in \meta{filename}.) -There's a shortcut version that sets \meta{filename} \cs{jobname}: -\begin{definition}[\DescribeMacro\GlsXtrLoadResources] -\cs{GlsXtrLoadResources}\oarg{options} -\end{definition} -(Only one instance of \cs{GlsXtrLoadResources} is permitted -per document. Use \cs{glsxtrresourcefile} for any additional -resources.) - -This writes the line -\begin{alltt} -\cs{glsxtr@resource}\marg{options}\marg{filename} -\end{alltt} -to the \texttt{.aux} file and will input -\meta{filename}\texttt{.glstex} if it exists.\footnote{v1.08 assumed -\meta{filename}\texttt{.tex} but that's potentially dangerous if, -for example, \meta{filename} happens to be the same as \cs{jobname}. -The \texttt{.glstex} extension was enforced by version 1.11.} The post-processor may use this information -to create the required file. (This is why the \pkgopt{record} -option automatically switches on \pkgopt[warn]{undefaction}, -to allow the document to compile before the post-processor -has created the \texttt{.glstex} file.) - -The options aren't processed by -\styfmt{glossaries-extra} (other than simply writing \meta{options} -to the \texttt{.aux} file). The post-processor determines the -allowed options. As from v1.11, this command also writes other -information to the \texttt{.aux} file for the benefit of the -post-processor, including the list of valid keys allowed by -\cs{newglossaryentry} so make sure you add any custom keys -before using \cs{glsxtrresourcefile} or \cs{GlsXtrLoadResources} -if the post-processor needs that information. - -\begin{definition}[\DescribeMacro\printunsrtglossary] -\cs{printunsrtglossary}\oarg{options} -\end{definition} -This behaves like \cs{printnoidxglossary} but never sorts the -entries and always lists all the defined entries for the given -glossary (and doesn't require \cs{makenoidxglossaries}). - -\begin{important} -You may use this command without the \pkgopt{record} option -or \cs{glsxtrresourcefile} if you're happy to have a complete -unsorted list without \glspl{numberlist}. However this requires -all entries to have been defined before use, so if you've used the -\pkgopt{docdefs} package option with definitions after the glossary, -you'll need a second \LaTeX\ run to pick up the definitions from the -\texttt{.glsdefs} file. -\end{important} - -The optional argument is as for \cs{printnoidxglossary} (except for -the \gloskey[printnoidxglossary]{sort} key, which isn't available). -The \gls{numberlist} will need setting by the post-processor -by adding the \gloskey{loclist} or \gloskey{location} field to the entry definitions, -otherwise the \gls*{numberlist} will be empty. (If both the -\gloskey{loclist} and \gloskey{location} fields are set, the -\gloskey{location} field will be used in the glossary.) - -The \gloskey{location} field should contain the relevant commands to -format the \gls{numberlist}. There's no specific syntax for this -field, it just needs to contain valid \LaTeX\ commands. - -The \gloskey{loclist} field should be a list separated by -\verb"|" (as per \sty{etoolbox}'s internal lists) where each -location in the list is in the format -\begin{definition} -\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location} -\end{definition} -(see the \styfmt{glossaries} manual for information about that -command). - -All glossaries may be displayed in the order of their definition -using: -\begin{definition}[\DescribeMacro\printunsrtglossaries] -\cs{printunsrtglossaries} -\end{definition} -which is analogous to \cs{printnoidxglossaries}. +file.) See \sectionref{sec:bib2gls} for further details. \item[{\pkgopt{docdef}}] This option governs the use of \cs{newglossaryentry}. It was originally a boolean option, @@ -668,9 +594,14 @@ the end of the document. Note that this necessarily adds to the overall document build time, especially if you have defined a large number of entries, so this defaults to \pkgoptfmt{false}, but it will be automatically switched on if you use the \gloskey{see} key in any -entries. To force it off, even if you use the \gloskey{see}, you +entries. To force it off, even if you use the \gloskey{see} key, you need to explicitly set \pkgopt{indexcrossrefs} to \pkgoptfmt{false}. +Note that \gls{bib2gls} can automatically find dependent +entries when it parses the \texttt{.bib} source file. +The \pkgopt{record} option automatically implements +\pkgopt[false]{indexcrossrefs}. + \item[{\pkgopt{abbreviations}}] This option has no value and can't be cancelled. If used, it will automatically create a new glossary with the label @@ -797,12 +728,81 @@ 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.) - -The \cs{newglossaryentry} command has a new key called -\gloskey{category}, which sets the category label for the given +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 an extra +key \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. + +The \cs{newglossaryentry} command has two new keys: +\begin{itemize} +\item \gloskey{category}, which sets the category label for the given entry. By default this is \texttt{general}. See \sectionref{sec:categories} for further information about categories. +\item \gloskey{alias}, which allows an entry to be alias to another +entry. See \sectionref{sec:alias} for further details. +\end{itemize} + +The \cs{longnewglossaryentry} command now has a starred version +(as from v1.12) that doesn't automatically insert +\begin{verbatim} +\leavevmode\unskip\nopostdesc +\end{verbatim} +at the end of the description field. +\begin{definition}[\DescribeMacro\longnewglossaryentry] +\cs{longnewglossaryentry}*\marg{label}\marg{options}\marg{description} +\end{definition} +The \gloskey{descriptionplural} key is left unset unless explicitly +set in \meta{options}. + +The unstarred version no longer hard-codes the above code (which +removes trailing space and suppresses the post-description hook) but instead +uses: +\begin{definition}[\DescribeMacro\glsxtrpostlongdescription] +\cs{glsxtrpostlongdescription} +\end{definition} +This can be redefined to allow the post-description hook to work +but retain the \cs{unskip} part if required. +For example: +\begin{verbatim} +\renewcommand*{\glsxtrpostlongdescription}{\leavevmode\unskip} +\end{verbatim} +This will discarded unwanted trailing space at the end of the description +but won't suppress the post-description hook. + +The unstarred version also alters the base \sty{glossaries} package's +treatment of the \gloskey{descriptionplural} key. Since a +plural description doesn't make much sense for multi-paragraph +descriptions, the default behaviour with +\sty{glossaries-extra}'s +\cs{longnewglossaryentry} is to simply leave the plural description +unset unless explicitly set using the \gloskey{descriptionplural} +key. The \styfmt{glossaries.sty} version of this command sets the description's +plural form to the same as the singular.\footnote{The +\gloskey{descriptionplural} key is a +throwback to the base package's original acronym mechanism before the introduction of +the \gloskey{long} and \gloskey{short} keys, where the long form was +stored in the \gloskey{description} field and the short form was stored in the +\gloskey{symbol} field.} + +Note that this modified unstarred version doesn't append +\cs{glsxtrpostlongdescription} to the description's plural form. The \ics{newterm} command (defined through the \pkgopt{index} package option) is modified so that the category defaults to \category{index}. @@ -1178,6 +1178,71 @@ 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} @@ -1203,6 +1268,92 @@ other categories will be unchanged. Further information about entry counting, including the new per-unit feature, is described in \sectionref{sec:entrycount}. +\section{Plurals} + +Some languages, such as English, have a general rule that plurals +are formed from the singular with a suffix appended. This isn't +an absolute rule. There are plenty of exceptions (for example, +geese, children, churches, elves, fairies, sheep). The +\sty{glossaries} package allows the \gloskey{plural} key to be +optional when defining entries. In some cases a plural may not make +any sense (for example, the term is a symbol) and in some cases +the plural may be identical to the singular. + +To make life easier for languages where the majority of plurals can +simply be formed by appending a suffix to the singular, the +\sty{glossaries} package sets lets the \gloskey{plural} field default +to the value of the \gloskey{text} field with \ics{glspluralsuffix} +appended. This command is defined to be just the letter \qt{s}. +This means that the majority of terms don't need to have the +\gloskey{plural} supplied as well, and you only need to use it for the +exceptions. + +For languages that don't have this general rule, the \gloskey{plural} +field will always need to be supplied, where needed. + +There are other plural fields, such as \gloskey{firstplural}, +\gloskey{longplural} and \gloskey{shortplural}. Again, if you are using +a language that doesn't have a simple suffix rule, you'll have to +supply the plural forms if you need them (and if a plural makes +sense in the context). + +If these fields are omitted, the \sty{glossaries} package follows +these rules: +\begin{itemize} +\item If \gloskey{firstplural} is missing, then \cs{glspluralsuffix} +is appended to the \gloskey{first} field, if that field has been +supplied. If the \gloskey{first} field hasn't been supplied but the +\gloskey{plural} field has been supplied, then the \gloskey{firstplural} +field defaults to the \gloskey{plural} field. If the \gloskey{plural} +field hasn't been supplied, then both the \gloskey{plural} and +\gloskey{firstplural} fields default to the \gloskey{text} field (or +\gloskey{name}, if no \gloskey{text} field) with \cs{glspluralsuffix} +appended. + +\item If the \gloskey{longplural} field is missing, then +\cs{glspluralsuffix} is appended to the \gloskey{long} field, if the +\gloskey{long} field has been supplied. + +\item If the \gloskey{shortplural} field is missing then, \emph{with +the base \sty{glossaries} acronym mechanism}, \ics{acrpluralsuffix} +is appended to the \gloskey{short} field. + +\end{itemize} + +This \emph{last case is changed} with \styfmt{glossaries-extra}. +With this extension package, the \gloskey{shortplural} field +defaults to the \gloskey{short} field with \ics{abbrvpluralsuffix} +appended unless overridden by category attributes. This +suffix command is set by the abbreviation styles. This means that +every time an abbreviation style is implemented, +\cs{abbrvpluralsuffix} is redefined. In most cases its redefined to +use +\begin{definition}[\DescribeMacro\glsxtrabbrvpluralsuffix] +\cs{glsxtrabbrvpluralsuffix} +\end{definition} +which defaults to just \cs{glspluralsuffix}. Some of the +abbreviation styles have their own command for the plural suffix, +such as \cs{glsxtrscsuffix} which is defined as: +\begin{verbatim} +\newcommand*{\glsxtrscsuffix}{\glstextup{\glsxtrabbrvpluralsuffix}} +\end{verbatim} +So if you want to completely strip all the plural suffixes used for +abbreviations then you need to redefine \cs{glsxtrabbrvpluralsuffix} +\emph{not} \cs{abbrvpluralsuffix}, which changes with the style. Redefining +\cs{acrpluralsuffix} will have no affect, since it's not used by the +new abbreviation mechanism. + +If you require a mixture (for example, in a multilingual document), +there are two attributes that affect the short plural suffix +formation. The first is \catattr{aposplural} which uses the suffix +\begin{verbatim} +'\abbrvpluralsuffix +\end{verbatim} +That is, an apostrophe followed by \cs{abbrvpluralsuffix} is +appended. The second attribute is \catattr{noshortplural} which +suppresses the suffix and simply sets \gloskey{shortplural} to the +same as \gloskey{short}. + \section{Nested Links} \label{sec:nested} @@ -1868,6 +2019,10 @@ want to suppress the page number (and only index the entry once). 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} @@ -3186,6 +3341,30 @@ use \ics{glsxtremfont}. 1.04, but original name retained as a deprecated synonym for backward-compatibility.) +\item[\abbrstyle{short-postlong-user}] +This style was introduced in version 1.12. It's like the +\abbrstyle{short-long-user} style but defers the parenthetical +material to after the link-text. This means that you don't have such +a long hyperlink (which can cause problems for the DVI \LaTeX\ format) +and it also means that the user supplied material can include a +hyperlink to another location. + +\item[\abbrstyle{short-postlong-user-desc}] +This style was introduced in version 1.12. It's like the above +\abbrstyle{short-postlong-user} style but the \gloskey{description} +must be specified. + +\item[\abbrstyle{long-postshort-user}] +This style was introduced in version 1.12. It's like the above +\abbrstyle{short-postlong-user} style but the long form is shown +first and the short form is in the parenthetical material (as for +\abbrstyle{long-short-user}) style. + +\item[\abbrstyle{long-postshort-user-desc}] +This style was introduced in version 1.12. It's like the above +\abbrstyle{long-postshort-user} style but the \gloskey{description} +must be specified. + \end{description} \section{Defining New Abbreviation Styles} @@ -4745,6 +4924,265 @@ don't use any commands in the \meta{label}, even if they expand to just text. \end{important} +\chapter{bib2gls: Managing Reference Databases} +\label{sec:bib2gls} + +There is a new command line application under development called +\gls{bib2gls}, which works in much the same way as \appfmt{bibtex}. +Instead of storing all your entry definitions in a \texttt{.tex} and +loading them using \cs{input} or \cs{loadglsentries}, the entries +can instead be stored in a \texttt{.bib} file and \gls{bib2gls} can +selectively write the appropriate commands to a \texttt{.glstex} +file which is loaded using \cs{glsxtrresourcefile} (or +\cs{GlsXtrLoadResources}). + +This means that you can use a reference managing system, such as +JabRef, to maintain the database and it reduces the \TeX\ overhead +by only defining the entries that are actually required in the +document. If you currently have a \texttt{.tex} file that contains +hundreds of definitions, but you only use a dozen or so in your +document, then the build time is needlessly slowed by the unrequired +definitions that occur when the file is input. + +Although \gls{bib2gls} isn't ready yet, there have been some new +commands and options added to \styfmt{glossaries-extra} to help +assist the integration of \gls{bib2gls} into the document build +process. + +An example of the contents of \texttt{.bib} file that stores +glossary entries that can be extracted with \gls{bib2gls}: +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal}, + see={[see also]{duck,goose}} +} + +@entry{duck, + name={duck}, + description = {a waterbird with short legs} +} + +@entry{goose, + name="goose", + plural="geese", + description={a waterbird with a long neck} +} +\end{verbatim} + +The follow provides some abbreviations: +\begin{verbatim} +@string{ssi={server-side includes}} +@string{html={hypertext markup language}} + +@abbreviation{shtml, + short="shtml", + long= ssi # " enabled " # html, + description={a combination of \gls{html} and \gls{ssi}} +} + +@abbreviation{html, + short ="html", + long = html, + description={a markup language for creating web pages} +} + +@abbreviation{ssi, + short="ssi", + long = ssi, + description={a simple interpreted server-side scripting language} +} +\end{verbatim} + +Here are some symbols: +\begin{verbatim} +preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"} + +@symbol{M, + name={$\mtx{M}$}, + text={\mtx{M}}, + description={a matrix} +} + +@symbol{v, + name={$\vec{v}$}, + text={\vec{v}}, + description={a vector} +} + +@symbol{S, + name={$\mathcal{S}$}, + text={\mathcal{S}}, + description={a set} +} +\end{verbatim} + +To ensure that \gls{bib2gls} can find out which entries have been +used in the document, you need the \pkgopt{record} package. Option: +\begin{verbatim} +\usepackage[record]{glossaries-extra} +\end{verbatim} +If this option's value is omitted (as above), the normal indexing +will be switched off, since \gls{bib2gls} can also sort the entries and +collate the locations. + +If you still want to use an indexing application (for example, you +need a custom \gls{xindy} rule), then just use +\pkgopt[alsoindex]{record} and continue to use \cs{makeglossaries} +and \cs{printglossary} (or \cs{printglossaries}), but instruct +\gls{bib2gls} to omit sorting to save time. + +The \texttt{.glstex} file created by \cs{bib2gls} is loaded using: +\begin{definition}[\DescribeMacro\glsxtrresourcefile] +\cs{glsxtrresourcefile}\oarg{options}\marg{filename} +\end{definition} +(Don't include the file extension in \meta{filename}.) +There's a shortcut version that sets \meta{filename} \cs{jobname}: +\begin{definition}[\DescribeMacro\GlsXtrLoadResources] +\cs{GlsXtrLoadResources}\oarg{options} +\end{definition} +On the first use, this command is a shortcut for +\begin{alltt} +\cs{glsxtrresourcefile}\oarg{options}\{\cs{jobname}\} +\end{alltt} +On subsequent use,\footnote{Version 1.11 only allowed one use +of \cs{GlsXtrLoadResources} per document.}\ this command is a shortcut for +\begin{alltt} +\cs{glsxtrresourcefile}\oarg{options}\{\cs{jobname}-\meta{n}\} +\end{alltt} +where \meta{n} is the current value of +\begin{definition} +\cs{glsxtrresourcecount} +\end{definition} +which is incremented at the end of \cs{GlsXtrLoadResources}. +Any advisory notes regarding \cs{glsxtrresourcefile} also +apply to \cs{GlsXtrLoadResources}. + +The \cs{glsxtrresourcefile} command writes the line +\begin{alltt} +\cs{glsxtr@resource}\marg{options}\marg{filename} +\end{alltt} +to the \texttt{.aux} file and will input +\meta{filename}\texttt{.glstex} if it exists.\footnote{v1.08 assumed +\meta{filename}\texttt{.tex} but that's potentially dangerous if, +for example, \meta{filename} happens to be the same as \cs{jobname}. +The \texttt{.glstex} extension was enforced by version 1.11.} + +The options are ignored by \styfmt{glossaries-extra} but are picked +up by \gls{bib2gls} and are used to supply various information, such +as the name of the \texttt{.bib} files and any changes to the +default behaviour. + +Since the \texttt{.glstex} won't exist on the first \LaTeX\ run, the +\pkgopt{record} package option additionally switches on +\pkgopt[warn]{undefaction}. Any use of commands like \cs{gls} or +\cs{glstext} will produce ?? in the document, since they are +undefined at this point. Once \gls{bib2gls} has created the +\texttt{.glstex} file the references should be resolved. + +Note that as from v1.12, \cs{glsxtrresourcefile} temporarily +switches the category code of \texttt{@} to 11 (letter) while it +reads the file to allow for any internal commands stored in the +location field. + +Since the \texttt{.glstex} file only defines those references used +within the document and the definitions have been written in the +order corresponding to \gls{bib2gls} sorted list, the glossaries can +simply be displayed using \cs{printunsrtglossary} (or +\cs{printunsrtglossaries}), described in \sectionref{sec:printunsrt}. + +Suppose the \texttt{.bib} examples shown above have been stored in +the files \texttt{terms.bib}, \texttt{abbrvs.bib} and +\texttt{symbols.bib} which may either be in the current directory or +on \TeX's path. Then the document might look like: +\begin{verbatim} +\documentclass{article} + +\usepackage[record]{glossaries-extra} + +\setabbreviationstyle{long-short-desc} + +\GlsXtrLoadResources[src={terms,abbrvs,symbols}] + +\begin{document} +\gls{bird} + +\gls{shtml} + +\gls{M} + +\printunsrtglossaries +\end{document} +\end{verbatim} +The document build process (assuming the document is called +\texttt{mydoc}) is: +\begin{verbatim} +pdflatex mydoc +bib2gls mydoc +pdflatex mydoc +\end{verbatim} +This creates a single glossary containing the entries: +\texttt{bird}, \texttt{duck}, \texttt{goose}, +\texttt{html}, \texttt{M}, \texttt{shtml} and \texttt{ssi} (in that +order). The \texttt{bird}, \texttt{shtml} and \texttt{M} entries +were added because \gls{bib2gls} detected (from the \texttt{.aux} +file) that they had been used in the document. The other entries +were added because \gls{bib2gls} detected (from the \texttt{.bib} +files) that they are referenced by the used entries. In the case of +\texttt{duck} and \texttt{goose}, they are in the \gloskey{see} +field for \texttt{bird}. In the case of \texttt{ssi} and +\texttt{html}, they are referenced in the \gloskey{description} +field of \texttt{shtml}. These cross-referenced entries won't have a +location list when the glossary is first displayed, but depending on +how they are referenced, they may pick up a location list on the +next document build. + +The entries can be separated into different glossaries with +different sort methods: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,abbreviations,symbols]{glossaries-extra} + +\setabbreviationstyle{long-short-desc} + +\GlsXtrLoadResources[src={terms},sort={en-GB},type=main] + +\glsxtrresourcefile + [src={abbrvs},sort={letter-nocase},type=abbreviations] + {\jobname-abr} + +\glsxtrresourcefile + [src={symbols},sort={use},type={symbols}] + {\jobname-sym} + +\begin{document} +\gls{bird} + +\gls{shtml} + +\gls{M} + +\printunsrtglossaries +\end{document} +\end{verbatim} +(By default, entries are sorted according to the operating system's +locale. If this doesn't match the document language, you need to +set this in the option list, for example \verb|sort=de-CH-1996| +for Swiss German using the new orthography.) + +Note that \cs{glsaddall} doesn't work in this case as it has to +iterate over the glossary lists, which will be empty on the first +run and on subsequent runs will only contain those entries that have +been selected by \gls{bib2gls}. Instead, if you want to add all +entries to the glossary, you need to tell \gls{bib2gls} this in the +options list: +\begin{verbatim} +\GlsXtrLoadResources[src={terms},selection={all}] +\end{verbatim} + +The \gls{bib2gls} user manual will contain more detail. + \chapter{Miscellaneous New Commands} \label{sec:miscnew} @@ -4758,39 +5196,571 @@ package provides a supplementary command that works in the same way except that it uses \ics{pageref} instead of \ics{ref}. -As mentioned in the description for the \pkgopt{record} package -option described in \sectionref{sec:pkgopts}, there's a new way of -printing a glossary without sorting or indexing: -\begin{definition} -\ics{printunsrtglossary}\oarg{options} +You can copy an entry to another glossary using +\begin{definition}[\DescribeMacro\glsxtrcopytoglossary] +\cs{glsxtrcopytoglossary}\marg{entry-label}\marg{glossary-type} +\end{definition} +This appends \meta{entry-label} to the end of the internal +list for the glossary given by \meta{glossary-type}. +Be careful if you use the \sty{hyperref} package as this +may cause duplicate hypertargets. You will need to change +\cs{glolinkprefix} to another value or disable hyperlinks +when you display the duplicate. Alternatively, use the new +\gloskey[printglossary]{target} key to switch off the targets: +\begin{verbatim} +\printunsrtglossary[target=false] +\end{verbatim} + +The \styfmt{glossaries} package allows you to set preamble code +for a given glossary type using \cs{setglossarypreamble}. This +overrides any previous setting. With \styfmt{glossaries-extra} +(as from v1.12) you can instead append to the preamble +using +\begin{definition}[\DescribeMacro\apptoglossarypreamble] +\cs{apptoglossarypreamble}\oarg{type}\marg{code} \end{definition} -To iterate over all glossaries: -\begin{definition} -\ics{printunsrtglossaries} +or prepend using +\begin{definition}[\DescribeMacro\pretoglossarypreamble] +\cs{pretoglossarypreamble}\oarg{type}\marg{code} \end{definition} -However, you can also uses these commands together with a -post-processor that works with the \pkgopt{record} package option and -\begin{definition} -\ics{glsxtrresourcefile}\oarg{options}{filename} +\section{Entry Fields} +\label{sec:fields} + +A field may now be used to store the name of a text-block command +that takes a single argument. The field is given by +\begin{definition}[\DescribeMacro\GlsXtrFmtField] +\cs{GlsXtrFmtField} +\end{definition} +The default value is \texttt{\GlsXtrFmtField}. Note that the +value must be the control sequence name \emph{without the initial +backslash}. + +For example: +\begin{verbatim} +\newcommand*{\mtx}[1]{\boldsymbol{#1}} +\newcommand*{\mtxinv}[1]{\mtx{#1}\sp{-1}} + +\newglossaryentry{matrix}{% + name={matrix}, + symbol={\ensuremath{\mtx{M}}}, + plural={matrices}, + user1={mtx}, + description={rectangular array of values} +} + +\newglossaryentry{identitymatrix}{% + name={identity matrix}, + symbol={\ensuremath{\mtx{I}}}, + plural={identity matrices}, + description={a diagonal matrix with all diagonal elements equal to +1 and all other elements equal to 0} +} + +\newglossaryentry{matrixinv}{% + name={matrix inverse}, + symbol={\ensuremath{\mtxinv{M}}}, + user1={mtxinv}, + description={a square \gls{matrix} such that + $\mtx{M}\mtxinv{M}=\glssymbol{identitymatrix}$} +} +\end{verbatim} + +There are two commands provided that allow you to apply the +command to an argument: +\begin{definition}[\DescribeMacro\glsxtrfmt] +\cs{glsxtrfmt}\oarg{options}\marg{label}\marg{text} +\end{definition} +This effectively does +\begin{alltt} +\cs{glslink}\oarg{options}\marg{label}\marg{\meta{cs}\marg{text}} +\end{alltt} +where \meta{cs} is the command obtained from the control +sequence name supplied in the provided field. If the field +hasn't been set, \cs{glsxtrfmt} will simply do \meta{text}. +The default \meta{options} are given by +\begin{definition}[\DescribeMacro\GlsXtrFmtDefaultOptions] +\cs{GlsXtrFmtDefaultOptions} +\end{definition} +This is defined as \texttt{\GlsXtrFmtDefaultOptions} but may +be redefined as appropriate. Note that the replacement text of +\cs{GlsXtrFmtDefaultOptions} is prepended to the optional +argument of \cs{glslink}. + +For example: +\begin{verbatim} +\[ + \glsxtrfmt{matrix}{A} + \glsxtrfmt{matrixinv}{A} + = + \glssymbol{identitymatrix} +\] +\end{verbatim} +If the default options are set to \texttt{noindex} then +\cs{glsxtrfmt} won't index, but will create a hyperlink (if +\sty{hyperref} has been loaded). This can be changed so that +it also suppresses the hyperlink: +\begin{verbatim} +\renewcommand{\GlsXtrFmtDefaultOptions}{hyper=false,noindex} +\end{verbatim} + +Note that \cs{glsxtrfmt} won't work with PDF bookmarks. Instead +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} +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. + +The \styfmt{glossaries} package provides \cs{glsaddstoragekey} to +add new keys. This command will cause an error if the key has +already been defined. The \styfmt{glossaries-extra} package provides +a supplementary command that will only define the key if it doesn't +already exist: +\begin{definition}[\DescribeMacro\glsxtrprovidestoragekey] +\cs{glsxtrprovidestoragekey}\marg{key}\marg{default}\marg{cs} +\end{definition} +If the key has already been defined, it will still provide the command given in +the third argument \meta{cs} (if it hasn't already been defined). Unlike +\cs{glsaddstoragekey}, \meta{cs} may be left empty if you're happy +to just use \cs{glsfieldfetch} to fetch the value of this new key. + +You can test if a key has been provided with: +\begin{definition}[\DescribeMacro\glsxtrifkeydefined] +\cs{glsxtrifkeydefined}\marg{key}\marg{true}\marg{false} +\end{definition} +This tests if \meta{key} is available for use in the +\meta{key}=\value{value} list in the second argument of +\cs{newglossaryentry} (or the optional argument of +commands like \cs{newabbreviation}). The corresponding +field may not have been set for any of the entries if no +default was provided. + +There are now commands provided to set individual fields. Note that +these only change the specified field, not any related fields. For +example, changing the value of the \gloskey{text} field won't update +the \gloskey{plural} field. + +\begin{definition}[\DescribeMacro\GlsXtrSetField] +\cs{GlsXtrSetField}\marg{label}\marg{field}\marg{value} +\end{definition} +Sets the field given by \meta{field} to \meta{value} for the entry +given by \meta{label}. No expansion is performed. It's not +necessary for the field to have been defined as a key. You +can access the value later with \cs{glsxtrusefield}. Note that +\cs{glsxtrifkeydefined} only tests if a key has been defined for use +with commands like \cs{newglossaryentry}. If a field without a +corresponding key is assigned a value, the key remains undefined. +This command is robust. + +\cs{GlsXtrSetField} uses +\begin{definition}[\DescribeMacro\glsxtrsetfieldifexists] +\cs{glsxtrsetfieldifexists}\marg{label}\marg{field}\marg{code} +\end{definition} +where \meta{label} is the entry label and \meta{code} is the +assignment code. + +This command just uses \ics{glsdoifexists}\marg{label}\marg{code} +(ignoring the \meta{field} argument), so by default it causes an +error if the entry doesn't exist. This can be changed to a warning +with \pkgopt[warn]{undefaction}. You can redefine +\cs{glsxtrsetfieldifexists} to simply do \meta{code} if you want to +skip the existence check. Alternatively you can instead use +\begin{definition}[\DescribeMacro\glsxtrdeffield] +\cs{glsxtrdeffield}\marg{label}\marg{field}\meta{arguments}\marg{replacement text} +\end{definition} +This simply uses \sty{etoolbox}'s \cs{csdef} without any checks. +This command isn't robust. There is also a version that uses +\cs{csedef} instead: +\begin{definition}[\DescribeMacro\glsxtredeffield] +\cs{glsxtredeffield}\marg{label}\marg{field}\meta{arguments}\marg{replacement text} +\end{definition} + +\begin{definition}[\DescribeMacro\gGlsXtrSetField] +\cs{gGlsXtrSetField}\marg{label}\marg{field}\marg{value} +\end{definition} +As \cs{GlsXtrSetField} but globally. + +\begin{definition}[\DescribeMacro\eGlsXtrSetField] +\cs{eGlsXtrSetField}\marg{label}\marg{field}\marg{value} +\end{definition} +As \cs{GlsXtrSetField} but uses protected expansion. + +\begin{definition}[\DescribeMacro\xGlsXtrSetField] +\cs{xGlsXtrSetField}\marg{label}\marg{field}\marg{value} +\end{definition} +As \cs{gGlsXtrSetField} but uses protected expansion. + +\begin{definition}[\DescribeMacro\GlsXtrLetField] +\cs{GlsXtrLetField}\marg{label}\marg{field}\marg{cs} +\end{definition} +Sets the field given by \meta{field} to the replacement text of \meta{cs} +for the entry given by \meta{label} (using \cs{let}). + +\begin{definition}[\DescribeMacro\csGlsXtrLetField] +\cs{csGlsXtrLetField}\marg{label}\marg{field}\marg{cs name} +\end{definition} +As \cs{GlsXtrLetField} but the control sequence name is supplied +instead. + +\begin{definition}[\DescribeMacro\GlsXtrLetFieldToField] +\cs{GlsXtrLetFieldToField}\marg{label-1}\marg{field-1}\marg{label-2}\marg{field-2} +\end{definition} +Sets the field given by \meta{field-1} for the entry given by +\meta{label-1} to the field given by \meta{field-2} for the entry +given by \meta{label-2}. There's no check for the existence of +\meta{label-2}, but +\cs{glsxtrsetfieldifexists}\marg{label-1}\marg{field-1}\marg{code} +is still used, as for \cs{GlsXtrSetField}. + +The \styfmt{glossaries} package provides \ics{glsfieldfetch} which +can be used to fetch the value of the given field and store it in a +control sequence. The \styfmt{glossaries-extra} package provides +another way of accessing the field value: +\begin{definition}[\DescribeMacro\glsxtrusefield] +\cs{glsxtrusefield}\marg{entry-label}\marg{field-label} +\end{definition} +This works in the same way as commands like \cs{glsentrytext} but +the field label is specified in the first argument. Note that the +\meta{field-label} corresponds to the internal field tag, which +isn't always the same as the key name. See Table~4.1 of the +\sty{glossaries} manual. No error occurs if the entry or field +haven't been defined. This command is not robust. + +There is also a version that converts the first letter to uppercase +(analogous to \cs{Glsentrytext}): +\begin{definition}[\DescribeMacro\Glsxtrusefield] +\cs{Glsxtrusefield}\marg{entry-label}\marg{field-label} +\end{definition} + +If you want to use a field to store a list that can be used +as an \sty{etoolbox} internal list, you can use the following +command that adds an item to the field using \sty{etoolbox}'s +\cs{listcsadd}: +\begin{definition}[\DescribeMacro\glsxtrfieldlistadd] +\cs{glsxtrfieldlistadd}\marg{label}\marg{field}\marg{item} +\end{definition} +where \meta{label} is the entry's label, \meta{field} is +the entry's field and \meta{item} is the item to add. There +are analogous commands that use \cs{listgadd}, \cs{listeadd} +and \cs{listxadd}: +\begin{definition}[\DescribeMacro\glsxtrfieldlistgadd] +\cs{glsxtrfieldlistgadd}\marg{label}\marg{field}\marg{item} +\end{definition} +\begin{definition}[\DescribeMacro\glsxtrfieldlisteadd] +\cs{glsxtrfieldlisteadd}\marg{label}\marg{field}\marg{item} +\end{definition} +\begin{definition}[\DescribeMacro\glsxtrfieldlistxadd] +\cs{glsxtrfieldlistxadd}\marg{label}\marg{field}\marg{item} +\end{definition} +You can then iterate over the list using: +\begin{definition}[\DescribeMacro\glsxtrfielddolistloop] +\cs{glsxtrfielddolistloop}\marg{label}\marg{field} \end{definition} or -\begin{definition} -\ics{GlsXtrLoadResources}\oarg{options} -\end{definition} -At the time of writing this, -there is a new post-processor under development called -\href{https://github.com/nlct/bib2gls}{bib2gls} that can be used in -this way to fetch glossary entries stored in a \texttt{.bib} file, -selecting only those referenced in the document. It then creates a -\texttt{.glstex} file with the relevant definitions defined in the -order indicated in by \meta{options}. Since the order of definition -is already in the appropriate order, there's no need for any -additional sorting by \gls{makeindex} or \gls{xindy}. (It is however -possible to use \gls{makeindex}\slash\gls{xindy} in combination -with the post-processor by setting \pkgopt[alsoindex]{record} and using -\cs{makeglossaries} and \cs{printglossaries} as usual. For example, -if you require custom \gls{xindy} rules.) +\begin{definition}[\DescribeMacro\glsxtrfieldforlistloop] +\cs{glsxtrfieldforlistloop}\marg{label}\marg{field}\marg{handler} +\end{definition} +that internally use \cs{dolistcsloop} and \cs{forlistloop}, +respectively. + +There are also commands that use \cs{ifinlistcs}: +\begin{definition}[\DescribeMacro\glsxtrfieldifinlist] +\cs{glsxtrfieldifinlist}\marg{label}\marg{field}\marg{item}\marg{true}\marg{false} +\end{definition} +and \cs{xifinlistcs} +\begin{definition}[\DescribeMacro\glsxtrfieldxifinlist] +\cs{glsxtrfieldxifinlist}\marg{label}\marg{field}\marg{item}\marg{true}\marg{false} +\end{definition} + +See the \sty{etoolbox}'s user manual for further +details of these commands, in particular the limitations +of \cs{ifinlist}. + +When using the \pkgopt{record} option, in addition to recording the +usual location, you can also record the current value +of another counter at the same time using the preamble-only command: +\begin{definition}[\DescribeMacro\GlsXtrRecordCounter] +\cs{GlsXtrRecordCounter}\marg{counter name} +\end{definition} +For example: +\begin{verbatim} +\usepackage[record]{glossaries-extra} +\GlsXtrRecordCounter{section} +\end{verbatim} +Each time an entry is referenced with commands like \cs{gls} +or \cs{glstext}, the \texttt{.aux} file will not only contain +the \cs{glsxtr@record} command but also +\begin{alltt} +\cs{glsxtr@counterrecord}\marg{label}\{section\}\marg{n} +\end{alltt} +where \meta{n} is the current expansion of \cs{thesection} +and \meta{label} is the entry's label. On the next run, when the +\texttt{.aux} file is run, this command will do +\begin{alltt} +\cs{glsxtrfieldlistgadd}\marg{label}\{record.\meta{counter}\}\marg{n} +\end{alltt} +In the above example, if \verb|\gls{bird}| is used in section~1.2 +this would be +\begin{verbatim} +\glsxtrfieldlistgadd{bird}{record.section}{1.2} +\end{verbatim} +Note that there's no key corresponding to this new +\texttt{record.section} field, but its value can be +accessed with \cs{glsxtrfielduse} or the list can be +iterated over with \cs{glsxtrfielddolistloop} etc. + +\section{Display All Entries Without Sorting or Indexing} +\label{sec:printunsrt} + +\begin{definition}[\DescribeMacro\printunsrtglossary] +\cs{printunsrtglossary}\oarg{options} +\end{definition} +This behaves like \cs{printnoidxglossary} but never sorts the +entries and always lists all the defined entries for the given +glossary (and doesn't require \cs{makenoidxglossaries}). + +There's also a starred form +\begin{definition}[\DescribeMacro\printunsrtglossary*] +\cs{printunsrtglossary}*\oarg{options}\marg{code} +\end{definition} +which is equivalent to +\begin{alltt} +\cs{begingroup} + \meta{code}\cs{printunsrtglossary}\oarg{options}\% +\cs{endgroup} +\end{alltt} +Note that unlike \cs{glossarypreamble}, the supplied \meta{code} is +done before the glossary header. + +This means you now have the option to simply list all entries on the +first \LaTeX\ run without the need for a post-processor, however +there will be no \gls{numberlist} in this case, as that has to be +set by a post-processor such as \gls{bib2gls} (see +\sectionref{sec:bib2gls}). + +For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries-extra} + +\newglossaryentry{zebra}{name={zebra},description={stripy animal}} +\newglossaryentry{ant}{name={ant},description={an insect}} + +\begin{document} +\gls{ant} and \gls{zebra} + +\printunsrtglossaries +\end{document} +\end{verbatim} +In the above, zebra will be listed before ant as it was defined +first. + +If you allow document definitions with the \pkgopt{docdefs} option, +the document will require a second \LaTeX\ run if the entries are +defined after \cs{printunsrtglossary}. + +The optional argument is as for \cs{printnoidxglossary} (except for +the \gloskey[printnoidxglossary]{sort} key, which isn't available). + +All glossaries may be displayed in the order of their definition +using: +\begin{definition}[\DescribeMacro\printunsrtglossaries] +\cs{printunsrtglossaries} +\end{definition} +which is analogous to \cs{printnoidxglossaries}. This just +iterates over all defined glossaries (that aren't on the ignored +list) and does \cs{printunsrtglossary}[type=\meta{type}]. + +The \cs{printunsrtglossary} command internally uses +\begin{definition}[\DescribeMacro\printunsrtglossaryhandler] +\cs{printunsrtglossaryhandler}\marg{label} +\end{definition} +for each item in the list, where \meta{label} is the current label. + +By default this just does +\begin{definition}[\DescribeMacro\glsxtrunsrtdo] +\cs{glsxtrunsrtdo}\marg{label} +\end{definition} +which determines whether to use \cs{glossentry} or +\cs{subglossentry} and checks the \gloskey{location} and +\gloskey{loclist} fields for the \gls{numberlist}. + +You can redefine the handler if required. + +\begin{important} +If you redefine the handler to exclude entries, you may end +up with an empty glossary. This could cause a problem for +the list-based styles. +\end{important} + +For example, if the preamble includes: +\begin{verbatim} +\usepackage[record,style=index]{glossaries-extra} +\GlsXtrRecordCounter{section} +\end{verbatim} +then you can print the glossary but first redefine the handler +to only select entries that include the current section number +in the \texttt{record.section} field: +\begin{verbatim} +\renewcommand{\printunsrtglossaryhandler}[1]{% + \glsxtrfieldxifinlist{#1}{record.section}{\thesection} + {\glsxtrunsrtdo{#1}}% + {}% +} +\end{verbatim} + +Alternatively you can use the starred form of +\cs{printunsrtglossary} which will localise the change: + +\begin{verbatim} +\printunsrtglossary*{% + \renewcommand{\printunsrtglossaryhandler}[1]{% + \glsxtrfieldxifinlist{#1}{record.section}{\thesection} + {\glsxtrunsrtdo{#1}}% + {}% + }% +} +\end{verbatim} + +If you are using the \sty{hyperref} package and want to +display the same glossary more than once, you can also +add a temporary redefinition of \cs{glolinkprefix} to +avoid duplicate hypertarget names. For example: + +\begin{verbatim} +\printunsrtglossary*{% + \renewcommand{\printunsrtglossaryhandler}[1]{% + \glsxtrfieldxifinlist{#1}{record.section}{\thesection} + {\glsxtrunsrtdo{#1}}% + {}% + }% + \ifcsundef{theHsection}% + {% + \renewcommand*{\glolinkprefix}{record.#2.\csuse{thesection}.}% + }% + {% + \renewcommand*{\glolinkprefix}{record.#2.\csuse{theHsection}.}% + }% +} +\end{verbatim} +If it's a short summary at the start of a section, you might +also want to suppress the glossary header and add some vertical +space afterwards: +\begin{verbatim} +\printunsrtglossary*{% + \renewcommand{\printunsrtglossaryhandler}[1]{% + \glsxtrfieldxifinlist{#1}{record.section}{\thesection} + {\glsxtrunsrtdo{#1}}% + {}% + }% + \ifcsundef{theHsection}% + {% + \renewcommand*{\glolinkprefix}{record.#2.\csuse{thesection}.}% + }% + {% + \renewcommand*{\glolinkprefix}{record.#2.\csuse{theHsection}.}% + }% + \renewcommand*{\glossarysection}[2][]{}% + \appto\glossarypostamble{\glspar\medskip\glspar}% +} +\end{verbatim} + +There's a shortcut command that does this: +\begin{definition}[\DescribeMacro\printunsrtglossaryunit] +\cs{printunsrtglossaryunit}\oarg{options}\marg{counter name} +\end{definition} +The above example can simply be replaced with: +\begin{verbatim} +\printunsrtglossaryunit{section} +\end{verbatim} + +This shortcut command is actually defined to use \cs{printunsrtglossary*} with +\begin{definition}[\DescribeMacro\printunsrtglossaryunitsetup] +\cs{printunsrtglossaryunitsetup}\marg{counter name} +\end{definition} +so if you want to just make some minor modifications you can +do +\begin{verbatim} +\printunsrtglossary*{\printunsrtglossaryunitsetup{section}% + \renewcommand*{\glossarysection}[2][]{\subsection*{Summary}}% +} +\end{verbatim} +which will start the list with a subsection header with the +title \qt{Summary} (overriding the glossary's title). + +Note that this shortcut command is only available with the +\pkgopt{record} (or \pkgopt[alsoindex]{record}) package option. + +This temporary change in the hypertarget prefix means you +need to explicitly use \cs{hyperlink} to create a link to it +as commands like \cs{gls} will try to link to the target +created with the default definition of \cs{gloslinkprefix}. +This isn't a problem if you want a primary glossary of all terms +produced using just \cs{printunsrtglossary} (in the front or back +matter) which can be the target for all glossary references +and then just use \cs{printunsrtglossaryunit} for a quick +summary at the start of a section etc. + +\section{Entry Aliases} +\label{sec:alias} + +An entry can be made an alias of another entry using the +\gloskey{alias} key. The value should be the label of the other +term. There's no check for the other's existence when the aliased +entry is defined. This is to allow the possibility of defining the +other entry after the aliased entry. (For example, when used with +\gls{bib2gls}.) + +If an entry \meta{entry-1} is made an alias of \meta{entry-2} then: +\begin{itemize} +\item If the \gloskey{see} field wasn't provided when \meta{entry-1} +was defined, the \gloskey{alias} key will automatically trigger +\begin{alltt} +\cs{glssee}\marg{entry-1}\marg{entry-2} +\end{alltt} +\item If the \sty{hyperref} package has been loaded then +\cs{gls}\marg{entry-1} will link to \meta{entry-2}'s target. (Unless +the \catattr{targeturl} attribute has been set for \meta{entry-1}'s +category.) +\item The \gloskey[glslink]{noindex} setting will automatically be triggered +when referencing \meta{entry-1} with commands like \cs{gls} or +\cs{glstext}. This prevents \meta{entry-1} from have a +\gls{locationlist} (aside from the cross-reference added with +\cs{glssee}) unless it's been explicitly indexed with \cs{glsadd} or +if the indexing has been explicitly set using +\texttt{noindex=false}. +\end{itemize} + +The index suppression trigger is performed by +\begin{definition}[\DescribeMacro\glsxtrsetaliasnoindex] +\cs{glsxtrsetaliasnoindex} +\end{definition} +This is performed after the default options provided by +\ics{GlsXtrSetDefaultGlsOpts} have been set. + +Within the definition of \cs{glsxtrsetaliasnoindex} you can use +\begin{definition}[\DescribeMacro\glsxtrindexaliased] +\cs{glsxtrindexaliased} +\end{definition} +to index \meta{entry-2}. + +The index suppression command can be redefined to index the main +term instead. For example: +\begin{verbatim} +\renewcommand{\glsxtrsetaliasnoindex}{% + \glsxtrindexaliased + \setkeys{glslink}{noindex}% +} +\end{verbatim} + +The value of the \gloskey{alias} field can be accessed using +\begin{definition}[\DescribeMacro\glsxtralias] +\cs{glsxtralias}\marg{label} +\end{definition} \chapter{Supplemental Packages} \label{sec:supplemental} @@ -5105,6 +6075,12 @@ and \cs{printnoidxglossary}. to allow for entries that should link to an external URL rather than to an internal glossary. +\item[sample-fmt.tex] Provides text-block commands associated +with entries in order to use \cs{glsxtrfmt}. + +\item[sample-alias.tex] Uses the \gloskey{alias} key. +(See \sectionref{sec:alias}.) + \item[sample-alttree.tex] Uses the \sty{glossaries-extra-stylemods} package with the \glostyle{alttree} style (see \sectionref{sec:stylemods}). |