diff options
author | Karl Berry <karl@freefriends.org> | 2018-04-29 23:02:25 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-04-29 23:02:25 +0000 |
commit | f8834f35084ceda8688cd138ef75fc19828c23f8 (patch) | |
tree | 7243deeaadd02abf5616bdb9b9eac279a29a9751 /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex | |
parent | a78005dad61adadbbd507e880a18b983baf7c90a (diff) |
glossaries-extra (25apr18)
git-svn-id: svn://tug.org/texlive/trunk@47494 c570f23f-e606-0410-a88d-b1316a301751
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.tex | 192 |
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 |