From e9af7499b89170ca5c737240b0cdb9563dcf6c5a Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Tue, 24 Mar 2020 03:02:47 +0000
Subject: CTAN sync 202003240302

---
 .../glossaries-extra/glossaries-extra-manual.tex   | 361 ++++++++++++++++++++-
 1 file changed, 356 insertions(+), 5 deletions(-)

(limited to 'macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex')

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}
 
-- 
cgit v1.2.3

