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.tex192
1 files changed, 188 insertions, 4 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 758d2a4c2f5..29754c4658a 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
@@ -226,13 +226,13 @@ styles (glossaries):>#1={\protect\ttfamily#1}|main}}
\DeleteShortVerb{\|}
\MakeShortVerb{"}
- \title{glossaries-extra.sty v1.29:
+ \title{glossaries-extra.sty v1.30:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2018-04-09}
+ \date{2018-04-25}
\maketitle
\begin{abstract}
@@ -796,6 +796,22 @@ duplicate page numbers present (but each page number will link to
the relevant part of the page where the indexing occurred). This
option automatically implements \pkgopt[wrglossary]{counter}.
+\begin{important}
+This option works by incrementing \ctr{wrglossary} and
+adding \ics{label}. This can cause a problem if the indexing
+occurs in an \env{equation} environment as \sty{amsmath}
+forbids multiple occurrences of \cs{label} (resulting in the
+\qt{Multiple \cs{label}'s} error). It's best to change the counter
+to \ctr{page} or \ctr{equation} when in maths mode with this option.
+For example:
+\begin{verbatim}
+\renewcommand{\glslinkpresetkeys}{%
+ \ifmmode \setkeys{glslink}{counter=equation}\fi}
+\renewcommand{\glsaddpresetkeys}{%
+ \ifmmode \setkeys{glossadd}{counter=equation}\fi}
+\end{verbatim}
+\end{important}
+
By default (with \sty{hyperref}), the page numbers in
\glspl{numberlist} link back to the top of the relevant page
(provided the format uses \cs{glshypernumber}). The
@@ -1331,6 +1347,14 @@ will use \cs{mathrel} instead of \cs{glstextformat} resulting in:
\end{alltt}
for entries with the \gloskey{category} key set to
\texttt{mathrelation}.
+
+\item[{\gloskey[glslink]{textformat}}] This key must have a
+control sequence name as its value. The command formed from
+this name must exist and must take one argument. (Use
+\texttt{relax} for default behaviour.) If set, this overrides
+the \catattr{textformat} attribute and \cs{glstextformat}.
+See the \sty{soul} example in \sectionref{sec:glsunset}.
+
\end{description}
There is a new hook that's used each time indexing information is
@@ -1353,6 +1377,33 @@ before the options are set by the \cs{gls}-like and
(The base package provides \ics{glslinkpostsetkeys} that's
used immediately after the options are set.)
+As from version 1.30 there are also similar hooks for \cs{glsadd}:
+\begin{definition}[\DescribeMacro\glsaddpresetkeys]
+\cs{glsaddpresetkeys}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glsaddpostsetkeys]
+\cs{glsaddpostsetkeys}
+\end{definition}
+For example, to default to using the \ctr{equation} counter in maths
+mode:
+\begin{verbatim}
+\renewcommand{\glslinkpresetkeys}{%
+ \ifmmode \setkeys{glslink}{counter=equation}\fi}
+\renewcommand{\glsaddpresetkeys}{%
+ \ifmmode \setkeys{glossadd}{counter=equation}\fi}
+\end{verbatim}
+(This can be overridden with an explicit use of
+\gloskey{counter} in the optional argument of \cs{gls} or
+\cs{glsadd}.) Alternatively, to enforce this (overriding the option
+argument):
+\begin{verbatim}
+\renewcommand{\glslinkpostsetkeys}{%
+ \ifmmode \setkeys{glslink}{counter=equation}\fi}
+\renewcommand{\glsaddpostsetkeys}{%
+ \ifmmode \setkeys{glossadd}{counter=equation}\fi}
+\end{verbatim}
+
As from version 1.14, there are two new keys for \cs{glsadd}:
\gloskey[glsadd]{thevalue} and \gloskey[glsadd]{theHvalue}.
These keys are designed for manually adding explicit locations
@@ -1686,6 +1737,14 @@ As from version 1.21, it's simpler to just do, for example:
\end{verbatim}
without redefining \cs{glsxtrregularfont}.
+As from version 1.30, there is also a command for abbreviations
+that encapsulates \cs{glsxtrgenabbrvfmt}:
+\begin{definition}[\DescribeMacro\glsxtrabbreviationfont]
+\cs{glsxtrabbreviationfont}\marg{text}
+\end{definition}
+This also just does its argument by default. Font changes
+made by abbreviation styles are within \meta{text}.
+
The \cs{glspostlinkhook} provided by the \styfmt{glossaries} package to
insert information after the \gls{linktext} produced by commands like \cs{gls} and \cs{glstext} is
redefined to
@@ -1969,6 +2028,124 @@ other categories will be unchanged.
Further information about entry counting, including the
new per-unit feature, is described in \sectionref{sec:entrycount}.
+\section{Unsetting the First Use Flag}
+\label{sec:glsunset}
+
+The internal command used by \cs{glsunset} is modified first to
+allow for the changing in entry counting, described above, but
+also to allow for buffering pending unsets when commands like
+\cs{gls} are used in a context where changing a boolean variable
+can cause things to go wrong. One example of this is using
+\cs{gls} in one of the commands provided with the \isty{soul}
+package. For example:
+\begin{verbatim}
+\ul{Some text about \gls{html}.}
+\end{verbatim}
+This causes the confusing error:
+\begin{verbatim}
+Glossary entry `{html}' has not been defined.
+\end{verbatim}
+The simplest workaround is to put \verb|\gls{html}| inside the
+argument of \cs{mbox}. For example:
+\begin{verbatim}
+\ul{Some text about \mbox{\gls{html}}.}
+\end{verbatim}
+This can work provided it's not the first use of this entry.
+It if is, then unsetting the first use flag causes a problem
+and results in the error:
+\begin{verbatim}
+! Package soul Error: Reconstruction failed.
+\end{verbatim}
+The \styfmt{glossaries-extra} package provides a way of temporarily
+switching off \cs{glsunset} so that it just makes a note of the
+entry's label but doesn't actually perform the change:
+\begin{definition}[\DescribeMacro\GlsXtrStartUnsetBuffering]
+\cs{GlsXtrStartUnsetBuffering}
+\end{definition}
+Later you can restore \cs{glsunset} and unset all buffered
+labels using:
+\begin{definition}[\DescribeMacro\GlsXtrStopUnsetBuffering]
+\cs{GlsXtrStopUnsetBuffering}
+\end{definition}
+The starred form \cs{GlsXtrStopUnsetBuffering*} uses
+\cs{glslocalunset} instead. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[T1]{fontenc}
+\usepackage{soul}
+\usepackage{glossaries-extra}
+
+\newabbreviation{html}{HTML}{hypertext markup language}
+
+\begin{document}
+\GlsXtrStartUnsetBuffering
+\ul{Some text about \mbox{\gls{html}}.}
+\GlsXtrStopUnsetBuffering
+
+Next use: \gls{html}.
+\end{document}
+\end{verbatim}
+
+\begin{important}
+Note that since the change in the first use flag now doesn't
+occur until \cs{GlsXtrStopUnsetBuffering}, multiple references
+of the same term within the buffering zone will always be
+treated as first use (if the term wasn't used before the
+buffering started).
+\end{important}
+
+There can still be a problem here as content within \cs{mbox}
+can't break across a line so you may end up with an overfull
+line or excessive white space within the paragraph.
+
+An alternative is to use \cs{protect}:
+\begin{verbatim}
+\GlsXtrStartUnsetBuffering
+\ul{Some text about \protect\gls{html}.}
+\GlsXtrStopUnsetBuffering
+\end{verbatim}
+but the formatting (underlining in this example) won't be applied.
+Another possibility is:
+\begin{verbatim}
+\usepackage[T1]{fontenc}
+\usepackage{soul}
+\usepackage{glossaries-extra}
+
+\newabbreviation{html}{HTML}{hypertext markup language}
+
+\newrobustcmd{\gul}[1]{%
+ {%
+ \def\glsxtrabbreviationfont##1{\GlsXtrExpandedFmt{\ul}{##1}}%
+ \def\glsxtrregularfont##1{\GlsXtrExpandedFmt{\ul}{##1}}%
+ #1%
+ }%
+}
+
+\begin{document}
+\ul{Some text about }\gls[textformat=gul]{html}.
+
+Next use: \gls{html}.
+\end{document}
+\end{verbatim}
+This moves \cs{gls} outside of \cs{ul} and uses
+\gloskey[glslink]{textformat} to locally change the formatting
+command used by \cs{gls} (which is normally given by
+\cs{glstextformat} or the \catattr{textformat} attribute)
+to a custom command \cs{gul}, which locally changes the regular font
+and the default abbreviation font to use \cs{ul}. It then uses
+\begin{definition}[\DescribeMacro\GlsXtrExpandedFmt]
+\cs{GlsXtrExpandedFmt}\marg{cs}\marg{text}
+\end{definition}
+which (protected) fully expands \meta{text} before applying
+\meta{cs}, which must be a control sequence that takes a single
+argument. This allows \cs{ul} to move much further inside
+and increases its chances of working. It can still break if
+\meta{text} expands to something that \cs{ul} can't deal with.
+For example, if an abbreviation style is used that contains
+complex formatting or if the field value contains problematic
+content.
+
\section{Plurals}
Some languages, such as English, have a general rule that plurals
@@ -2123,7 +2300,7 @@ This produces:
\begin{quote}
The sample files are either hypertext markup language (HTML) or
server
-side includes (SSI) enabled HTML (SHTML), but let’s first discuss
+side includes (SSI) enabled HTML (SHTML), but let's first discuss
SSI.
\end{quote}
So the \gls{firstuse} of the \texttt{shtml} entry now produces
@@ -4399,6 +4576,12 @@ where \meta{text} is the short form (for the
\abbrstyle{short-long-user} style). This command first inserts
a space using \cs{glsxtrfullsep} and then the parenthetical content
(using \ics{glsxtrparen}).
+The \gloskey{description} is set to
+\begin{definition}[\DescribeMacro\glsuserdescription]
+\cs{glsuserdescription}\marg{long}\marg{label}
+\end{definition}
+The default definition ignores the \meta{label} and encapsulates
+\meta{long} with \cs{glslonguserfont}.
The \gloskey{name} is obtained by expanding
\cs{glsxtrlongshortname} (see above).
@@ -4581,7 +4764,8 @@ obtained by expanding
\end{definition}
Again, this should only be redefined before \cs{newabbreviation} (or
\cs{newacronym}) and commands that should be expanded need to be
-protected.
+protected. The \gloskey{description} is set to
+\cs{glsuserdescription}\marg{long}\marg{label}.
\item[\abbrstyledef{short-nolong-desc-noreg}]
This style is like \abbrstyle{short-nolong-desc} but it doesn't