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.tex179
1 files changed, 140 insertions, 39 deletions
diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.tex
index 0920f2ff4c..2702311b17 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.45:
+ \title{glossaries-extra.sty v1.46:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2020-04-01}
+ \date{2021-09-20}
\maketitle
\begin{abstract}
@@ -248,6 +248,9 @@ package. (The base \styfmt{glossaries} package provides additional files,
but this one needs \styfmt{glossaries-extra}.) There are equivalent
\texttt{.bib} files for use with \gls{bib2gls}.
+\textbf{The \styfmt{glossaries-extra} package uses a different set
+of defaults to the base \styfmt{glossaries} package.} See the
+Introduction for more details.
\end{abstract}
\begin{important}
@@ -351,6 +354,10 @@ option is switched on. To revert to using the \sty{translator}
interface, use \pkgopt[true]{translate}. There is no change to the
default if \sty{babel} hasn't been loaded.
+\item The default style used by \ics{newacronym} is
+\abbrstyle{short-nolong}. (That is, the long form is not shown on
+\gls{firstuse}.)
+
\end{itemize}
The examples below illustrate the difference in explicit
@@ -360,7 +367,7 @@ resulting from modifications to commands provided by
\styfmt{glossaries} (see \sectionref{sec:modifications}).
\begin{enumerate}
-\item
+\item Basic defaults:
\begin{verbatim}
\documentclass{article}
\usepackage{glossaries-extra}
@@ -372,7 +379,7 @@ This is like:
\usepackage{glossaries-extra}
\end{verbatim}
-\item
+\item Language defaults:
\begin{verbatim}
\documentclass[british]{article}
\usepackage{babel}
@@ -386,7 +393,7 @@ This is like:
\usepackage{glossaries-extra}
\end{verbatim}
-\item
+\item Combined with \cls{memoir}
\begin{verbatim}
\documentclass{memoir}
\usepackage{glossaries-extra}
@@ -412,6 +419,33 @@ This is like:
Since by the time \styfmt{glossaries-extra} has been loaded,
\styfmt{glossaries} has already redefined \cls{memoir}'s
glossary-related commands.
+
+\item Abbreviations are defined with \cs{newabbreviation}:
+\begin{verbatim}
+\usepackage{glossaries-extra}
+\newabbreviation{svm}{SVM}{support vector machine}
+\begin{document}
+First use: \gls{svm}. Explicit full form: \glsxtrfull{svm}.
+\end{document}
+\end{verbatim}
+This is the closest to:
+\begin{verbatim}
+\usepackage{glossaries}
+\newacronym{svm}{SVM}{support vector machine}
+\begin{document}
+First use: \gls{svm}. Explicit full form: \acrfull{svm}.
+\end{document}
+\end{verbatim}
+If you want to continue using \cs{newacronym} then you will need to
+change the style for the \category{acronym} category:
+\begin{verbatim}
+\usepackage{glossaries-extra}
+\setabbreviationstyle[acronym]{long-short}
+\newacronym{svm}{SVM}{support vector machine}
+\begin{document}
+First use: \gls{svm}. Explicit full form: \glsxtrfull{svm}.
+\end{document}
+\end{verbatim}
\end{enumerate}
Another noticeable change is that by default \cs{printglossary}
@@ -545,7 +579,7 @@ The \pkgopt[showwrgloss]{debug} option implements
\end{definition}
to show a mark \ensuremath{\cdot} just before the write operation
performed by the indexing commands. If you use
-\pkgopt[alsoindex]{record} there will be a mark for the
+\pkgopt[hybrid]{record} there will be a mark for the
write operation to the \texttt{.aux} file for \gls{bib2gls}
and a mark for the write operation to the associated glossary
file for \gls{makeindex} or \gls{xindy}.
@@ -730,7 +764,9 @@ the package option \pkgoptfmt{seenoindex=ignore} (provided by
\item[{\pkgoptdef{record}}]\label{opt:record}(New to v1.08.) This is
a \meta{key}=\meta{value} option provided for the benefit of
-\gls{bib2gls} (see \sectionref{sec:bib2gls}).
+\gls{bib2gls} (see \sectionref{sec:bib2gls}). If you want to use
+\gls{bib2gls}, the recommended setting is \pkgopt[nameref]{record}
+if you have hyperlinks and \pkgopt[only]{record} if you don't have hyperlinks.
The option may only be set in the preamble and can't be used after
\cs{GlsXtrLoadResources}. If the value is missing
@@ -740,7 +776,7 @@ The option may only be set in the preamble and can't be used after
is performed as normal using either \cs{makeglossaries}
or \cs{makenoidxglossaries}. This setting implements \pkgopt[error]{undefaction}.
-\item[\pkgoptfmt{only}] The indexing is performed by
+\item[\pkgoptfmt{only}] The indexing (recording) is performed by
\gls{bib2gls} (see \sectionref{sec:bib2gls}). Neither
\cs{makeglossaries} nor \cs{makenoidxglossaries} is permitted.
This setting implements \pkgopt[warn]{undefaction} and automatically
@@ -757,6 +793,13 @@ pdflatex myDoc
bib2gls myDoc
pdflatex myDoc
\end{verbatim}
+If you want letter groups you will need the \verb|--group|
+or \verb|-g| switch when invoking \gls{bib2gls}:
+\begin{verbatim}
+pdflatex myDoc
+bib2gls -g myDoc
+pdflatex myDoc
+\end{verbatim}
Note that \pkgopt[only]{record} will prevent the \gloskey{see} from
automatically implementing \cs{glssee}. (\gls{bib2gls} deals with the
@@ -788,20 +831,35 @@ location list. If the indexing counter is the default
\ctr{page}, only the location number is shown. Similarly for
\pkgopt[equation]{counter} (or \pkgopt[true]{equations}).
-\item[\pkgoptfmt{alsoindex}] This is a hybrid setting
+\item[\pkgoptfmt{alsoindex}] Deprecated synonym of \pkgoptfmt{hybrid}.
+
+\item[\pkgoptfmt{hybrid}] This is a hybrid setting
that uses \gls{bib2gls} to fetch entry information from
\texttt{.bib} files, but uses \gls{makeindex} or \gls{xindy}
-to create the glossary files. This option should be used
-with \cs{makeglossaries} but not with its optional argument.
-This option should not be used with \cs{makenoidxglossaries}.
-You may need to change the transcript file used by \gls{bib2gls}
-to avoid a clash with the transcript file used by
-\gls{makeindex} or \gls{xindy}. (This can be done with
+to create the glossary files (which are input with \ics{printglossary}).
+Note that this requires a slower and more complicated build process
+(see below).
+
+This hybrid approach is provided for the rare instances
+where an existing \gls{xindy} rule or module is too complicated to convert to
+a \gls{bib2gls} rule but the entries need to be fetched from a
+\filetype{bib} file. There's no benefit in using this option with \gls{makeindex}.
+
+\begin{important}
+Since it's redundant to make \gls{bib2gls} also sort, use \texttt{sort=none} in
+\cs{GlsXtrLoadResources} for a faster build.
+\end{important}
+
+This option must be used with \ics{makeglossaries} but not with
+its optional argument. This option should not be used with
+\cs{makenoidxglossaries}. You may need to change the transcript
+file used by \gls{bib2gls} to avoid a clash with the transcript file
+used by \gls{makeindex} or \gls{xindy}. (This can be done with
\gls{bib2gls}['s] \verb|--log-file| or \verb|-t| option.)
-The glossaries should be displayed using \cs{printglossary}
-(or \cs{printglossaries}). This option is expected to be used with
-\gls{bib2gls}'s \texttt{sort=none} setting and so
+Each glossary should be displayed using \cs{printglossary} (or
+\cs{printglossaries} for all of them). This option is expected to be
+used with \gls{bib2gls}'s \texttt{sort=none} setting and so
\sty{glossaries-extra-bib2gls} is not automatically loaded.
The document build process is (assuming the file is called
@@ -813,18 +871,26 @@ pdflatex myDoc
makeglossaries myDoc
pdflatex myDoc
\end{verbatim}
+Note that, in this case, it's redundant to call \gls{bib2gls} with the
+\verb|--group| or \verb|-g| switch as \gls{makeindex}/\gls{xindy}
+will insert the group heading information into the corresponding
+glossary file. (If you want \gls{bib2gls} to form the letter groups
+then this hybrid method is inappropriate.)
\end{description}
-With the recording on (\pkgopt[only]{record} or
-\pkgopt[alsoindex]{record}), 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.
-\gls{bib2gls} can then read these lines to find
-out which entries have been used. (Remember that commands like
+With the recording on (\pkgopt[only]{record},
+\pkgopt[nameref]{record} or \pkgopt[hybrid]{record}), 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. \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.) See \sectionref{sec:bib2gls} for further details.
+The hybrid method additionally performs the standard indexing action
+that's required for \gls{makeindex} or \gls{xindy} to work.
+
\item[{\pkgoptdef{equations}}] (New to v1.37.) This option will
cause the default location counter to automatically switch
to \ctr{equation} when inside a numbered equation environment, such
@@ -981,6 +1047,14 @@ entries may be defined in the preamble or anywhere in the document,
but they may only be referenced after they have been defined.
Entries must be defined before the associated glossary is displayed.
+If you need a list of all entry labels for the use of an editor or
+helper script you may also want to consider the package options
+\pkgopt{writeglslabels} and \pkgopt{writeglslabelnames} provided by
+the base \sty{glossaries} package. Note that with these options
+and \pkgopt[atom]{docdef}, only the entry labels visible to \LaTeX\ can
+be saved. So if you are using \gls{bib2gls} you will only get the
+labels of the entries that are selected by \gls{bib2gls}.
+
\end{itemize}
The \styfmt{glossaries} package allows
@@ -1301,8 +1375,8 @@ otherwise \meta{list} can be a comma-separated list of glossaries
that need processing with an external indexing application.
This command is not permitted with the \pkgopt[only]{record}
-package option. Without the optional argument, it's permitted
-with \pkgopt[alsoindex]{record}. With the optional argument,
+package option. Without the optional argument, it's required
+with \pkgopt[hybrid]{record}. With the optional argument,
it's only permitted with the default \pkgopt[off]{record}.
It should then be possible to use \cs{printglossary} for those
@@ -1739,12 +1813,7 @@ the \gloskey{see} value is simply used to directly
write a line to the corresponding glossary file and is then
discarded. This is why the \gloskey{see} key can't be
used before \ics{makeglossaries} (since the file hasn't been opened
-yet). It's also the reason why the \gloskey{see} key doesn't have
-any effect when used in entries that are defined in the
-\env{document} environment. Since the value isn't saved,
-it's not available when the \texttt{.glsdefs} file is created at the
-end of the document and so isn't available at the start of the
-\env{document} environment on the next run.
+yet).
This modification allows \styfmt{glossaries-extra} to provide
\begin{definition}[\DescribeMacro\glsxtraddallcrossrefs]
@@ -1754,8 +1823,8 @@ which is used at the end of the document to automatically add
any unused cross-references unless the package option
\pkgopt{indexcrossrefs} was set to false.
-As a by-product of this enhancement, the \gloskey{see} key will now
-work for entries defined in the \env{document} environment, but it's still
+Note that even though the \gloskey{see} key will now
+work for entries defined in the \env{document} environment, it's still
best to define entries in the preamble, and the \gloskey{see} key
still can't perform any indexing before the file has been opened by
\cs{makeglossaries}. Note that \styfmt{glossaries} v4.24 introduced
@@ -3156,7 +3225,9 @@ 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.
+offset. This can cause odd results but can be switched off with
+\gloskey[false]{groups}. See \href{https://dickimaw-books.com/gallery/index.php?label=bib2gls-inner}{Gallery: Inner or Nested
+Glossaries} for an example.
\end{itemize}
\subsection{Glossary Style Modifications}
@@ -3648,6 +3719,27 @@ will insert section-level bookmarks. The use of \cs{currentglossary}
helps to provide unique bookmark labels in the event of multiple
glossaries.
+The \sty{glossary-tree} package provides the commands
+\begin{definition}[\DescribeMacro\glstreepredesc]
+\cs{glstreepredesc}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glstreechildpredesc]
+\cs{glstreechildpredesc}
+\end{definition}
+(which both default to a space) and uses them in the \glostyle{tree}-like
+styles, but not for the \glostyle{alttree} style. The
+\sty{glossaries-extra-stylemods} package modifies the
+\glostyle{alttree} style so that it has equivalent hooks:
+\begin{definition}[\DescribeMacro\glsalttreepredesc]
+\cs{glsalttreepredesc}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glsalttreechildpredesc]
+\cs{glsalttreechildpredesc}
+\end{definition}
+These do nothing by default.
+
The \glostyle{index}-like and \glostyle{tree}-like styles
insert the pre-\gls{numberlist} space with
\begin{definition}[\DescribeMacro\glstreeprelocation]
@@ -4752,6 +4844,15 @@ the name. Level~$n$ sub-entries have the name indented by
$(n-1)\times$\cs{glstopicSubIndent}. The hanging indent depends
on whether or not a widest name has been set for the level.
+As from v1.46, there is also a length for additional indentation
+used in the second paragraph onwards for child entries with
+multi-paragraph descriptions:
+\begin{definition}[\DescribeMacro\glstopicSubItemParIndent]
+\cs{glstopicSubItemParIndent}
+\end{definition}
+This is initialised to \ics{parindent} when \sty{glossary-topic} is
+loaded.
+
\begin{definition}[\DescribeMacro\glstopicInit]
\cs{glstopicInit}
\end{definition}
@@ -8860,7 +8961,7 @@ 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}
+\pkgopt[hybrid]{record} and continue to use \cs{makeglossaries}
and \cs{printglossary} (or \cs{printglossaries}), but you also need
to instruct \gls{bib2gls} to omit sorting to save time and
to prevent the \gloskey{sort} key from being set.
@@ -9163,7 +9264,7 @@ The package option \pkgopt[only]{record} (or simply \pkgopt{record})
automatically loads the supplementary package
\sty{glossaries-extra-bib2gls}, which provides some commands
that are specific to \gls{bib2gls}. The package isn't
-loaded by \pkgopt[alsoindex]{record} as that option is intended
+loaded by \pkgopt[hybrid]{record} as that option is intended
for sorting with \gls{makeindex} or \gls{xindy} and it is expected
that the sorting will be switched off (with the resource option
\texttt{sort=none}).
@@ -11640,7 +11741,7 @@ 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.
+\pkgopt{record} (or \pkgopt[hybrid]{record}) package option.
This temporary change in the hypertarget prefix means you
need to explicitly use \cs{hyperlink} to create a link to it
@@ -12177,7 +12278,7 @@ was defined, the \gloskey{alias} key will automatically trigger
\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 With \pkgopt[off]{record} or \pkgopt[alsoindex]{record}, the \gloskey[glslink]{noindex} setting will automatically be triggered
+\item With \pkgopt[off]{record} or \pkgopt[hybrid]{record}, 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