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 | 361 |
1 files changed, 356 insertions, 5 deletions
diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex index d5676e39a4..b720b1aaa0 100644 --- a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex +++ b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex @@ -225,13 +225,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}} \DeleteShortVerb{\|} \MakeShortVerb{"} - \title{glossaries-extra.sty v1.43: + \title{glossaries-extra.sty v1.44: an extension to the glossaries package} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} - \date{2020-02-28} + \date{2020-03-23} \maketitle \begin{abstract} @@ -3122,6 +3122,41 @@ label before the glossary using: \cs{glsxtrsetglossarylabel}\marg{label} \end{definition} but take care of duplicate labels if it's not scoped. + +\item +\gloskey[printunsrtglossary]{groups}. This is a boolean key (new to +v1.44) designed for use with \cs{printunsrtglossary} (and other +\cs{printunsrt\ldots} variations). It has no +effect with \cs{printglossary} and \cs{printnoidxglossary}. + +If true (default), group formation (group header and group skip) +will be attempted if the \gloskey{group} key has been defined and set. Note +that some styles ignore the header and group skip commands so there +may not be a noticeable difference in those cases. If this key is +set to false, no group formation will occur so there won't be any +group markup to separate letter groups so there will be no visual +separation regardless of style or the group skip setting. + +\item +\gloskey[printunsrtglossary]{leveloffset}. This key (new to +v1.44) is designed for use with \cs{printunsrtglossary} (and other +\cs{printunsrt\ldots} variations). It has no +effect with \cs{printglossary} and \cs{printnoidxglossary}. + +The value may either be a simple integer \meta{n} to indicate assignment or in the form +\texttt{++\meta{n}} to indicate an increment. This will locally +assign or increment the level offset. The default value is~0. This +will cause entries to be displayed as though their hierarchical +level is $N$ more than it would normally be (where $N$ is the level +offset). For example, a top-level entry (that is, an entry without a +parent) would normally have a hierarchical level of~0. With a level +offset of~1, it would be treated by the glossary style as though it +was actually a level~1 entry. (Remember that some styles don't +support hierarchical glossaries.) + +Note that the group formation (if supported) will still occur +between entries that don't have a parent, regardless of the level +offset. This can cause odd results. \end{itemize} \subsection{Glossary Style Modifications} @@ -5235,7 +5270,7 @@ The provided shortcut commands listed in \bfseries Shortcut & \bfseries Shortcut & \bfseries Equivalent Command\\ -\bfseries (\pkgopt[abbreviation]{shortcuts}) & +\bfseries (\pkgopt[abbreviations]{shortcuts}) & \bfseries (\pkgopt[ac]{shortcuts})\\ \ics{ab} & \ics{ac} & \ics{cgls}\\ \ics{abp} & \ics{acp} & \ics{cglspl}\\ @@ -11357,7 +11392,10 @@ a header or a vertical separation.) If the \gloskey{group} field is non-empty, then the corresponding title is obtained as described earlier. -If you want to use a different field, you can redefine +In either case, if the \gloskey[printunsrtglossary]{groups} option is set +to false then no group formation will be performed. + +If you want to use a different field for the group label, you can redefine \begin{definition}[\DescribeMacro\glsxtrgroupfield] \cs{glsxtrgroupfield} \end{definition} @@ -11409,6 +11447,9 @@ 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}]. +\subsection{Hooks} +\label{sec:printunsrthooks} + To avoid complications caused by \env{tabular}-like glossary styles, \cs{printunsrtglossary} iterates over all entries in the selected glossary and appends the appropriate code @@ -11464,7 +11505,10 @@ You can instruct \gls{bib2gls} to omit setting the \gloskey{loclist} field with the resource option \texttt{--save-loclist=false} to prevent it from being used as a fallback. -You can redefine the handler if required. For example, +\subsection{Filtering} +\label{sec:printunsrtfilter} + +You can redefine the handler used by \cs{printunsrtglossary} if required. For example, you may want to filter entries according to the category label. You can test if a label is contained in a comma-separated list of labels using: @@ -11608,6 +11652,313 @@ 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{Partial Glossaries} +\label{sec:printunsrtinner} + +It's possible that you may require greater customisation over the +way the glossary is displayed that can't be simply achieved with the +hooks or glossary styles. This section describes a command and +environment provided to assist with this, but note that they aren't +compatible with tabular-like glossary styles, such as +\glostyle{long} or \glostyle{super}, due to their complexity and +internal scoping that interferes with alignment. You will also need +to take care with list styles (provided in the \sty{glossary-list} +package). + +To get a better understanding of how this works, it's useful to +consider how a glossary with \gls{makeindex} works. Here's a simple +example document: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\makeglossaries + +\newglossaryentry{cabbage}{name={cabbage}, + description={vegetable with thick green or purple leaves}} + +\newglossaryentry{broccoli}{name={broccoli}, + description={vegetable with heads of small green or purple flower buds}} + +\begin{document} +\Gls{cabbage} and \gls{broccoli}. + +\printglossary +\end{document} +\end{verbatim} +When the document is built, \gls{makeindex} creates a file that +contains: +\begin{alltt} +\ics{glossarysection}[\ics{glossarytoctitle}]\mgroup{\ics{glossarytitle}}\ics{glossarypreamble} +\cs{begin}\mgroup{theglossary}\ics{glossaryheader} +\ics{glsgroupheading}\mgroup{B}\cs{relax} \ics{glsresetentrylist} +\ics{glossentry}\mgroup{broccoli}\marg{location list}\ics{glsgroupskip} +\ics{glsgroupheading}\mgroup{C}\cs{relax} \ics{glsresetentrylist} +\ics{glossentry}\mgroup{cabbage}\marg{location list}\% +\cs{end}\mgroup{theglossary}\ics{glossarypostamble} +\end{alltt} +The \cs{printglossary} command defines the commands shown +above after it's detected the glossary type, the title and style. It +then inputs the file. + +The \cs{printunsrtglossary} command performs the same preliminary +setup but there's no file to input. Instead it then does the section +heading (\cs{glossarysection}) and preamble (\cs{glossarypreamble}) +and constructs a control sequence that contains +\texttt{\cs{begin}\mgroup{theglossary}} \meta{content} +\texttt{\cs{end}\mgroup{theglossary}}. + +The letter group markup (\cs{glsgroupheading} and \cs{glsgroupskip}) +is inserted whenever the group label changes between top-level +entries. In this case, \meta{content} doesn't explicitly contain +\cs{glossentry} but uses a handler function instead. For example, +instead of: +\begin{alltt} +\ics{glossentry}\mgroup{broccoli}\marg{location list} +\end{alltt} +the \meta{content} will contain: +\begin{alltt} +\meta{internal handler}\mgroup{broccoli} +\end{alltt} +This internal handler uses \ics{printunsrtglossaryhandler} to +determine the required information (location list, hierarchical +level) that's needed to typeset the entry (using \cs{glossentry} or +\cs{subglossentry}). + +\begin{definition} +\cs{begin}\mgroup{printunsrtglossarywrap}\oarg{options}\newline +\meta{content} +\cs{end}\mgroup{printunsrtglossarywrap} +\end{definition} +The \env{printunsrtglossarywrap} environment provides a wrapper in +which you can place the actual glossary code. The optional argument +is the same as for \cs{printunsrtglossary}, but note that in this +case the \gloskey[printglossary]{type} key simply provides the +glossary title and doesn't identify the content. + +This environment essentially does: +\begin{alltt} +\meta{initial setup} +\ics{glossarysection}[\ics{glossarytoctitle}]\mgroup{\ics{glossarytitle}}\ics{glossarypreamble} +\cs{begin}\mgroup{theglossary}\ics{glossaryheader}\cs{glsresetentrylist} +\meta{content} +\cs{end}\mgroup{theglossary}\cs{glossarypreamble} +\end{alltt} +where \meta{initial setup} is much the same code as used by +\cs{printglossary} and \cs{printunsrtglossary}. Most importantly, +\meta{initial setup} sets the current glossary style, which +determines the definition of \env{theglossary}, \cs{glossentry} and +\cs{subglossentry}. + +Whilst it is possible to explicitly use the commands that create +letter group headings and the handler within \meta{content}, it +would be quite laborious and prone to error to do so for anything +other than a very short list. This can be illustrated with the +following silly example: +\begin{verbatim} +\begin{printunsrtglossarywrap}[style=indexgroup]% +\glsgroupheading{W}% +\gdef\glscurrententrylabel{cabbage}% +\printunsrtglossaryhandler\glscurrententrylabel +\glsgroupskip +\glsgroupheading{Z}% +\gdef\glscurrententrylabel{broccoli}% +\printunsrtglossaryhandler\glscurrententrylabel +\end{printunsrtglossarywrap} +\end{verbatim} +This trivial example will work with a tabular-like style, such as +\glostyle{long} (although the group headings will be ignored). A +more practical example that uses a loop within \meta{content} won't. + +\begin{definition} +\ics{printunsrtinnerglossary}\oarg{options}\marg{pre-code}\marg{post-code} +\end{definition} +This command is provided for use within +\env{printunsrtglossarywrap}. The optional argument \meta{options} +is similar to \cs{printunsrtglossary} but the following keys are +unavailable: \gloskey[printglossary]{title}, +\gloskey[printglossary]{toctitle}, \gloskey[printglossary]{style}, +\gloskey[printglossary]{numberedsection} and \gloskey[printglossary]{label}. + +This will do: +\begin{alltt} + \cs{begingroup} + \meta{initial setup} + \meta{pre-code} + \meta{content} + \meta{post-code} + \cs{endgroup} +\end{alltt} +where \meta{initial setup} processes the options and assigns +\ics{currentglossary}, \meta{pre-code} is some preliminary code and +\meta{post-code} is some final code before the end of the scoping. +The \meta{content} is the sequence of code that +\cs{printunsrtglossary} would normally insert within the +\env{theglossary} environment. + +For example: +\begin{verbatim} +\begin{printunsrtglossarywrap}[style=indexgroup] +\printunsrtinnerglossary[type=main]{}{} +\end{printunsrtglossarywrap} +\end{verbatim} +This produces a result very similar to that obtained with just: +\begin{verbatim} +\printunsrtglossary[style=indexgroup,type=main] +\end{verbatim} +The first case is unsuitable for use with a tabular-style. It will +also cause a problem with a list style when used with \gls{bib2gls} +(where the inner content will be empty on the first \LaTeX\ run +which will cause a missing \cs{item} error). + +This partial glossary command is more useful when you need to apply +filtering (which can be set up in the \meta{pre-code} argument as in +\cs{printunsrtglossary*}) or if you have multiple glossaries. For +example: +\begin{verbatim} +\begin{printunsrtglossarywrap}[style=list] +\item[Animals] +\printunsrtinnerglossary[type=animal]{}{} +\item[Vegetables] +\printunsrtinnerglossary[type=vegetable]{}{} +\item[Minerals] +\printunsrtinnerglossary[type=mineral]{}{} +\end{printunsrtglossarywrap} +\end{verbatim} +In this case, the \glostyle{list} style doesn't cause a problem as +there will be three instances of \cs{item} on the first \LaTeX\ run. + +Here's another example: +\begin{verbatim} +\begin{printunsrtglossarywrap}[style=indexgroup] +\glsgroupheading{animal}% +\printunsrtinnerglossary[type=animal]{}{} +\glsgroupskip +\glsgroupheading{vegetable}% +\printunsrtinnerglossary[type=vegetable]{}{} +\glsgroupskip +\glsgroupheading{mineral}% +\printunsrtinnerglossary[type=mineral]{}{} +\end{printunsrtglossarywrap} +\end{verbatim} +Note that in both of the above cases, the inner glossaries have been +arranged manually (animal, then vegetable and then mineral). + +It's also possible to use \cs{printunsrtinnerglossary} within the +handler function used by \cs{printunsrtglossary}. The internal +scoping within \cs{printunsrtinnerglossary} helps to reduce +interference. + +This is a rather more complicated example that requires +\gls{bib2gls}. Suppose I have a file called +\nolinkurl{topictitles.bib} that contains: +\begin{verbatim} +@indexplural{animal} +@indexplural{mineral} +@indexplural{vegetable} +\end{verbatim} +And also a file called \nolinkurl{topics.bib} that contains entries +like: +\begin{verbatim} +@entry{zebra, + name={zebra}, + description={striped African horse}, + category={animal} +} + +@entry{broccoli, + name={broccoli}, + description={vegetable with heads of small green or purple flower buds}, + category={vegetable} +} + +@entry{quartz, + name={quartz}, + description={hard mineral consisting of silica}, + category={mineral} +} +\end{verbatim} +Note that the category labels in the second file match the entry +labels in the first file. + +The simplest way of creating a hierarchical glossary from this data +is to input both files and copy the \gloskey{category} field to the +\gloskey{parent} field: +\begin{verbatim} +\GlsXtrLoadResources[src={topictitles,topics}, + replicate-fields={category=parent}] +\end{verbatim} +The glossary can then simply be displayed with: +\begin{verbatim} +\printunsrtglossary[style=indexgroup] +\end{verbatim} +This will now be ordered: animal (followed by animal child entries), +mineral (followed by mineral child entries), vegetable (followed by +vegetable child entries). + +Suppose (for some strange reason) that I now need the ordering to be +vegetable, mineral, animal (that is, reverse alphabetical) but the +child entries still need to be in the normal alphabetical order. + +It's not possible to use different sort methods for different +hierarchical levels with \gls{bib2gls}, but it is possible to +simulate it. + +Instead of making the entries within \nolinkurl{topics.bib} children +of the entries defined in \nolinkurl{topictitles.bib}, I'm now going +to create separate glossaries for each type: +\begin{verbatim} +\newignoredglossary*{animal} +\newignoredglossary*{mineral} +\newignoredglossary*{vegetable} +\end{verbatim} +The entries in \nolinkurl{topictitles.bib} go in the default main +glossary and are sorted in reverse: +\begin{verbatim} +\GlsXtrLoadResources[src=topictitles,type=main,selection=all, + sort=en-GB-reverse] +\end{verbatim} +Note that I've selected all entries in this example. It becomes more +complicated with the default selection criteria. (See the +\nolinkurl{sample-nested.tex} example provided with \gls{bib2gls} +v2.3+.) + +Now the entries in \nolinkurl{topics.bib} are selected but the +\gloskey{type} field is set to the \gloskey{category} field: +\begin{verbatim} +\GlsXtrLoadResources[src=topics,type={same as category},selection=all, + sort=en-GB] +\end{verbatim} +The aim here is to use \cs{printunsrtglossary} to list all the +entries in the main glossary (that is, all the topic titles) and use +a handler that tests if there is a glossary that has the same label +as the current entry label. If one exists, it's then listed using +\cs{printunsrtinnerglossary} with the level offset shifted to give a +hierarchical appearance: +\begin{verbatim} +\newcommand{\nestedhandler}[1]{% + \glsxtrunsrtdo{#1}% + \ifglossaryexists*{#1}% + {% + \printunsrtinnerglossary[type={#1},leveloffset=++1]{}{}% + }% + {}% +} + +\printunsrtglossary*[type=main,style=index]{% + \let\printunsrtglossaryhandler\nestedhandler +} +\end{verbatim} + +I've used \cs{newignoredglossary*} as I don't need to specify a +title for any of those glossaries nor do I need to use those glossaries with +\cs{printunsrtglossaries}. With \gls{bib2gls} v2.3+, I can omit the +three \cs{newignoredglossary*} lines and use the +\texttt{-{}-provide-glossaries} switch which will make \gls{bib2gls} +automatically provide any unknown glossaries (with +\cs{provideignoredglossary}) in the \texttt{.glstex} file. + \section{Standalone Entry Items} \label{sec:glossentry} |