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 | 126 |
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] |