summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex103
1 files changed, 94 insertions, 9 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
index 8bb21a52cf5..96fb37ddb5d 100644
--- a/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
+++ b/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
@@ -210,13 +210,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.22:
+ \title{glossaries-extra.sty v1.23:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2017-11-08}
+ \date{2017-11-12}
\maketitle
\begin{abstract}
@@ -925,7 +925,8 @@ set the shortcuts provided by the \styfmt{glossaries} package for
acronyms (such as \cs{ac}). Note that the short and long forms don't
use \cs{glsxtrshort} and \cs{glsxtrlong} but use the original
\cs{acrshort} and \cs{acrlong}, which don't recognise multiple
-abbreviation styles.
+abbreviation styles. The better option with \styfmt{glossaries-extra}
+is \pkgopt[ac]{shortcuts}.
\item \pkgopt[ac]{shortcuts}:
set the shortcuts provided by the \styfmt{glossaries} package for
@@ -953,7 +954,8 @@ The \qt{other} shortcuts are:
\end{itemize}
\item \pkgopt[all]{shortcuts} (or \pkgopt[true]{shortcuts}):
-implements both \pkgopt[ac]{shortcuts} and \pkgopt[other]{shortcuts}
+implements \pkgopt[ac]{shortcuts}, \pkgopt[abbreviations]{shortcuts}
+and \pkgopt[other]{shortcuts}.
\item \pkgopt[none]{shortcuts} (or \pkgopt[false]{shortcuts}):
don't define any of the shortcut commands (default).
@@ -988,7 +990,14 @@ post-description punctuation. It doesn't suppress the use of
category-dependent post-description hooks. (Note that the
punctuation, which is in the original base hook \cs{glspostdescription},
comes after the extended post-description hook
-\cs{glsxtrpostdescription} not before.)
+\cs{glsxtrpostdescription} not before.) The post-description hook
+can counter-act the effect of \cs{glsxtrnopostpunc} using
+\begin{definition}[\DescribeMacro\glsxtrrestorepostpunc]
+\cs{glsxtrrestorepostpunc}
+\end{definition}
+These commands have no effect outside of the glossary (except with
+standalone entries that use \cs{glsxtractivatenopost} and
+\cs{glspostdescription}, see \sectionref{sec:glossentry}).
The \styfmt{glossaries} package provides
\begin{definition}[\DescribeMacro\glsseeitemformat]
@@ -1615,6 +1624,22 @@ if a full stop hasn't be discarded and
\end{definition}
if a full stop has been discarded.
+It may be that you want to check some other setting (rather
+than a category attribute) to determine whether or not to discard
+a following full stop. In which case you can redefine:
+\begin{definition}[\DescribeMacro\glsxtrifcustomdiscardperiod]
+\cs{glsxtrifcustomdiscardperiod}\marg{true}\marg{false}
+\end{definition}
+You can access the field's label using \cs{glslabel}.
+This command should do \meta{true} if the post-link hook
+should check if a period follows and \meta{false} otherwise.
+The default definition is simply:
+\begin{verbatim}
+\newcommand*{\glsxtrifcustomdiscardperiod}[2]{#2}
+\end{verbatim}
+which means that no additional checks are performed.
+(Only the recognised category attributes will be checked.)
+
\begin{important}
Avoid the use of \cs{gls}-like and \cs{glstext}-like commands
within the post-link hook as they will cause interference.
@@ -3045,6 +3070,25 @@ a localised effect. For a global setting, use
\begin{definition}[\DescribeMacro\xglssetwidest]
\cs{xglssetwidest}\oarg{level}\marg{name}
\end{definition}
+The following only set the value if \meta{name} is wider than the
+current value (new to version 1.23). Local update:
+\begin{definition}[\DescribeMacro\glsupdatewidest]
+\cs{glsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+Global update:
+\begin{definition}[\DescribeMacro\gglsupdatewidest]
+\cs{gglsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+Locale update (expands \meta{name}):
+\begin{definition}[\DescribeMacro\eglsupdatewidest]
+\cs{eglsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+Global update (expands \meta{name}):
+\begin{definition}[\DescribeMacro\xglsupdatewidest]
+\cs{xglsupdatewidest}\oarg{level}\marg{name}
+\end{definition}
+
+
The widest entry value can later be retrieved using
\begin{definition}[\DescribeMacro\glsgetwidestname]
\cs{glsgetwidestname}
@@ -7289,12 +7333,14 @@ command to an argument:
\end{definition}
This effectively does
\begin{alltt}
-\cs{glslink}\oarg{options}\marg{label}\{\meta{cs}\marg{text}\}
+\cs{glslink}[\meta{default-options},\meta{options}]\marg{label}\{\cs{glsxtrfmtdisplay}\marg{text}\{\}\}
\end{alltt}
where \meta{cs} is the command obtained from the control
-sequence name supplied in the provided field. If the field
-hasn't been set, \cs{glsxtrfmt} will simply do \meta{text}.
-The default \meta{options} are given by
+sequence name supplied in the provided field, which must be defined
+to take a single required argument. Although it effectively
+acts like \cs{glslink} it misses out the post-link hook.
+
+The default \meta{default-options} are given by
\begin{definition}[\DescribeMacro\GlsXtrFmtDefaultOptions]
\cs{GlsXtrFmtDefaultOptions}
\end{definition}
@@ -7303,6 +7349,38 @@ be redefined as appropriate. Note that the replacement text of
\cs{GlsXtrFmtDefaultOptions} is prepended to the optional
argument of \cs{glslink}.
+As from version 1.23, there's also a starred version of
+this command that has a final optional argument:
+\begin{definition}[\DescribeMacro{\glsxtrfmt*}]
+\cs{glsxtrfmt*}\oarg{options}\marg{label}\marg{text}\oarg{insert}
+\end{definition}
+Both the starred and unstarred versions use:
+\begin{definition}[\DescribeMacro\glsxtrfmtdisplay]
+\cs{glsxtrfmtdisplay}\marg{cs name}\marg{text}\marg{insert}
+\end{definition}
+within the link text.
+In the case of the unstarred version \meta{insert} will be empty.
+It will also be empty if the final option argument is
+missing from the starred form. If the entry given by \meta{label}
+is undefined \cs{glsxtrfmt} and \cs{glsxtrfmt*} will issue
+an error (or warning if \pkgopt[warn]{undefaction}).
+There won't be a warning or error if the entry is defined by
+the given field is missing. In either case,
+(the entry is undefined or the field is missing) \meta{cs name}
+will be \texttt{@firstofone} otherwise it will be the
+field value. The default definition is:
+\begin{verbatim}
+\newcommand{\glsxtrfmtdisplay}[3]{\csuse{#1}{#2}#3}
+\end{verbatim}
+which puts \meta{text} inside the argument of the control sequence
+and \meta{insert} outside it (but it will still be inside the
+link text).
+
+\begin{important}
+Remember that nested links cause a problem so avoid using
+commands like \cs{gls} or \cs{glsxtrfmt} within \meta{text}.
+\end{important}
+
For example:
\begin{verbatim}
\[
@@ -7457,6 +7535,13 @@ The starred version
\end{definition}
omits the implicit grouping.
+There is also a version that simply uses \cs{ifcsundef}. It
+doesn't save the field value, but can be used if you only
+need to check if the field is defined without accessing it:
+\begin{definition}[\DescribeMacro\GlsXtrIfFieldUndef]
+\cs{GlsXtrIfFieldUndef}\marg{field}\marg{label}\marg{true}\marg{false}
+\end{definition}
+
You can test if a field value equals a string using
\begin{definition}[\DescribeMacro{\GlsXtrIfFieldEqStr}]
\cs{GlsXtrIfFieldEqStr}\marg{label}\marg{field}\marg{text}\marg{true}\marg{false}