summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r--macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex126
1 files changed, 106 insertions, 20 deletions
diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
index 2702311b17..5f47addf84 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.46:
+ \title{glossaries-extra.sty v1.47:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2021-09-20}
+ \date{2021-11-04}
\maketitle
\begin{abstract}
@@ -2049,6 +2049,23 @@ For convenience, \styfmt{glossaries-extra} provides
\end{definition}
which fully expands its argument and passes it to \cs{glsseelist}.
+As from v1.47, \styfmt{glossaries-extra} redefines \cs{glsseelist}
+to make it more flexible. The base package provides
+\cs{glsseeitem}\marg{label} which is used to format each element in
+the list and \cs{glsseelastsep} for the separator between the final
+two items (\cs{glsseesep} is used between the other items). The
+modifications provide two additional commands:
+\begin{definition}[\DescribeMacro\glsseefirstitem]
+\cs{glsseefirstitem}\marg{label}
+\end{definition}
+This defaults to \cs{glsseeitem}\marg{label} and is used to format
+the first label in the list.
+\begin{definition}[\DescribeMacro\glsseelastoxfordsep]
+\cs{glsseelastoxfordsep}
+\end{definition}
+This defaults to \cs{glsseelastsep} and is used if the list consists
+of three or more labels.
+
The \gloskey{seealso} key implements the automatic indexing using
\begin{definition}[\DescribeMacro\glsxtrindexseealso]
\cs{glsxtrindexseealso}\marg{label}\marg{xr list}
@@ -3230,7 +3247,7 @@ offset. This can cause odd results but can be switched off with
Glossaries} for an example.
\end{itemize}
-\subsection{Glossary Style Modifications}
+\section{Glossary Style Modifications}
\label{sec:glosstylemods}
The \sty{glossaries-extra-stylemods} package (more conveniently
@@ -3265,19 +3282,19 @@ you can use
\cs{glsxtrlocalsetgrouptitle}\marg{label}\marg{title}
\end{definition}
-\subsubsection{Style Hooks}
+\subsection{Style Hooks}
\label{sec:stylehooks}
The commands \ics{glossentryname} and \ics{glossentrydesc} are
modified to take into account the \catattr{glossname},
-\category{glossnamefont}, \catattr{glossdesc} and \catattr{glossdescfont}
+\catattr{glossnamefont}, \catattr{glossdesc} and \catattr{glossdescfont}
attributes (see \sectionref{sec:categories}). This means you can
make simple font or case-changing modifications to the name and description
without defining a new glossary style.
(New to version 1.42.)
The command \ics{glossentrysymbol} is modified to take into account
-the \catattr{glosssymbolfont}. Note that, unlike the above, there's
+the \catattr{glosssymbolfont} attribute. Note that, unlike the above, there's
no corresponding attribute to change the case as it's usually not
appropriate to change the case of a symbol (and for some symbols,
such as pictographs, there's no concept of case). If
@@ -3323,13 +3340,13 @@ of \gloskey{name}, you can use
\begin{definition}[\DescribeMacro\glossentrynameother]
\cs{glossentrynameother}\marg{label}\marg{field}
\end{definition}
-This behaves just like \cs{glossentryname} (that is, it obeys
-\catattr{glossname}, \catattr{glossnamefont} or \cs{glsnamefont} and uses the post-name
-hook) but it uses the given \meta{field} instead of \gloskey{name}.
-The \meta{field} argument must be the internal field name
-(for example \texttt{desc} rather than \texttt{description}).
-See the key to field mappings table in the \styfmt{glossaries}
-user manual.
+This behaves just like \cs{glossentryname} (that is, it obeys the
+\catattr{glossname} attribute, uses either the \catattr{glossnamefont}
+attribute or \cs{glsnamefont} to format the text, and uses the post-name hook)
+but it uses the given \meta{field} instead of \gloskey{name}. The
+\meta{field} argument must be the internal field name (for example
+\texttt{desc} rather than \texttt{description}). See the key to
+field mappings table in the \styfmt{glossaries} user manual.
There is a hook after \ics{glossentryname} and
\ics{Glossentryname}:
@@ -3430,7 +3447,7 @@ the predefined styles provided by \styfmt{glossaries} that are missing
\cs{glspostdescription}.
\end{important}
-\subsubsection{Number List}
+\subsection{Number List}
\label{sec:glosstylenumlist}
The \gls{numberlist} is now placed inside the argument of
@@ -3543,7 +3560,7 @@ doesn't display any differently from
but it does make it easier to define your own custom list handler
that can accommodate the ranges.
-\subsubsection{The \styfmt{glossaries-extra-stylemods} Package}
+\subsection{The \styfmt{glossaries-extra-stylemods} Package}
\label{sec:stylemods}
As from v1.02, \styfmt{glossaries-extra} now includes the package
@@ -3581,6 +3598,8 @@ Remember to group the value if it contains any commas:
\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra}
\end{verbatim}
+\paragraph{Inline Style}
+
Note that the \glostyle{inline} style is dealt with slightly
differently. The original definition provided by the
\sty{glossary-inline} package uses \cs{glspostdescription} at the
@@ -3595,6 +3614,8 @@ that the modified \glostyle{inline} style isn't affected by the
\pkgopt{nopostdot} option, but the post-description category hook
can still be used.
+\paragraph{Tabular Styles}
+
The \env{tabular}-like styles, such as \glostyle{long} are
adjusted so that the \ics{ifglsnogroupskip} conditional (set with
\pkgopt{nogroupskip}) is moved outside of the definition of
@@ -3618,6 +3639,8 @@ For example:
\renewcommand{\glsxtrprelocation}{\dotfill}
\end{verbatim}
+\paragraph{List Styles}
+
The \glostyle{list} styles use
\begin{definition}[\DescribeMacro\glslistprelocation]
\cs{glslistprelocation}
@@ -3636,6 +3659,27 @@ is governed by:
for the \glostyle{list} and \glostyle{altlist} styles (but not the
\glostyle{listdotted} variations).
+As from v1.47, the item is governed by:
+\begin{definition}[\DescribeMacro\glslistitem]
+\cs{glslistitem}\marg{label}
+\end{definition}
+The \glostyle{altlist} styles use:
+\begin{definition}[\DescribeMacro\glsaltlistitem]
+\cs{glsaltlistitem}\marg{label}
+\end{definition}
+which internally uses \cs{glslistitem}.
+The header item (for the list styles that should the group title) is governed by:
+\begin{definition}[\DescribeMacro\glslistgroupheaderitem]
+\cs{glslistgroupheaderitem}\marg{group-label}\marg{header code}
+\end{definition}
+This ignores the \meta{group-label} by default and simply places the
+second argument in the optional argument of \cs{item}. The
+\meta{header code} is the formatted group title, possibly including
+a hypertarget. The spacing after the group item is given by:
+\begin{definition}[\DescribeMacro\glslistgroupafterheader]
+\cs{glslistgroupafterheader}
+\end{definition}
+
For just the \glostyle{list} style and its letter group variations
(not the \glostyle{altlist} or \glostyle{listdotted} variations) the
\gls{numberlist} for child entries is followed by
@@ -7757,10 +7801,14 @@ The attribute may have one of the following values:
\item \texttt{firstuc}: the first letter of the description will be
converted to upper case (using \ics{Glsentrydesc}).
-\item \texttt{title}: the description will be used in the argument of the
-title casing command \ics{capitalisewords} (provided by
-\sty{mfirstuc}). If you want to use a different command
-you can redefine:
+\item \texttt{title}: the description will be used in the argument
+of the title casing command. If you have at least
+\styfmt{glossaries} v4.48, the title casing is indirectly performed
+by \cs{glscapitalisewords}, which defaults to \ics{capitalisewords}
+(provided by \sty{mfirstuc}). You can either redefine
+\cs{glscapitalisewords} if you want the change to also affect
+\ics{glsentrytitlecase} or if you only want the change to apply to
+the attribute case-changing then redefine:
\begin{definition}[\DescribeMacro\glsxtrfieldtitlecasecs]
\cs{glsxtrfieldtitlecasecs}\marg{phrase cs}
\end{definition}
@@ -7996,6 +8044,12 @@ This uses \cs{glssetcategoryattribute} with \cs{glscategory} to set
the attribute. Note that this will affect all other entries that
share this entry's category.
+The above use local assignments so they can be placed inside a group
+to limit their definition. As from v1.47, the value can be unset using:
+\begin{definition}[\DescribeMacro\glsunsetcategoryattribute]
+\cs{glsunsetcategoryattribute}\marg{category-label}\marg{attribute-label}
+\end{definition}
+
You can fetch the value of an attribute for a particular category
using:
\begin{definition}[\DescribeMacro\glsgetcategoryattribute]
@@ -9559,6 +9613,8 @@ This internally uses \cs{GlsXtrIfFieldNonZero} and will do
\meta{false} if the field isn't set. Within \meta{true} and
\meta{false} you can use \cs{glscurrentfieldvalue} to access the
value. (It will be 0 in \meta{false} if the field isn't set.)
+As from v1.47, there is also a starred version which uses
+\cs{GlsXtrIfFieldNonZero*} (don't add grouping).
A convenient shortcut for use in the \texttt{entry-type-aliases}
@@ -11056,6 +11112,18 @@ This command isn't robust. There is also a version that uses
\cs{glsxtredeffield}\marg{label}\marg{field}\meta{arguments}\marg{replacement text}
\end{definition}
+The following command was added to \styfmt{glossaries-extra} v1.47
+primarily for the convenience of \gls{bib2gls}:
+\begin{definition}[\DescribeMacro\glsxtrapptocsvfield]
+\cs{glsxtrapptocsvfield}\marg{label}\marg{field}\marg{value}
+\end{definition}
+There's no check for the existence of either the entry or the field.
+If the entry identified by \meta{label} has the given field set then
+this command will append a comma followed by \meta{value} to the
+existing value, otherwise it will set the field to just
+\meta{value}. This uses \cs{csdef} or \cs{csappto} so the effect can
+be localised.
+
\begin{definition}[\DescribeMacro\gGlsXtrSetField]
\cs{gGlsXtrSetField}\marg{label}\marg{field}\marg{value}
\end{definition}
@@ -11206,6 +11274,21 @@ accordingly. As from version 1.39, these numeric tests have
starred versions. The unstarred versions add implicit grouping.
The starred versions don't.
+As from v1.47 there's a similar command:
+\begin{definition}[\DescribeMacro\GlsXtrIfValueInFieldCsvList]
+\cs{GlsXtrIfValueInFieldCsvList}\marg{label}\marg{field}\marg{value}\marg{true}\marg{false}
+\end{definition}
+This is essentially the opposite situation where the list is stored
+in the given field and \meta{value} is the element to find in the
+list. Again the unstarred versions add implicit grouping. Note that
+the \meta{value} isn't expanded. If you need it to be fully expanded
+before searching for it use:
+\begin{definition}[\DescribeMacro\xGlsXtrIfValueInFieldCsvList]
+\cs{xGlsXtrIfValueInFieldCsvList}\marg{label}\marg{field}\marg{value}\marg{true}\marg{false}
+\end{definition}
+(To add a value to a field containing a comma-separated list, use
+\cs{glsxtrapptocsvfield}. To iterate over the field use \cs{glsxtrforcsvfield}.)
+
To test if the value is non-zero:
\begin{definition}[\DescribeMacro{\GlsXtrIfFieldNonZero}]
\cs{GlsXtrIfFieldNonZero}\marg{field}\marg{label}\marg{true}\marg{false}
@@ -11342,7 +11425,10 @@ a user level command:
which is just a synonym for \cs{@endfortrue}.
The loop is performed within the true part of \cs{glsxtrifhasfield}
-so scoping is automatically applied.
+so scoping is automatically applied. If you don't want scoping use
+\cs{glsxtrforcsvfield*} which will use \cs{glsxtrifhasfield*}
+instead but take care if you nest these starred commands as
+unexpected results can occur without the scoping.
New to v1.42:
\begin{definition}[\DescribeMacro\glsxtrfieldformatcsvlist]