summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-01-05 21:49:40 +0000
committerKarl Berry <karl@freefriends.org>2018-01-05 21:49:40 +0000
commit5add5510b8b8121f5575f0c8cc8397a36abb3eab (patch)
tree73404b86be8e89ade21b16da0d34c5fec5c3f77f /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex
parentfe0e333e467cf6e0d1a533da3ff7caa679aeb1dc (diff)
glossaries-extra (5jan18)
git-svn-id: svn://tug.org/texlive/trunk@46225 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.tex305
1 files changed, 273 insertions, 32 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 e770711e475..d4934849ac1 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.25:
+ \title{glossaries-extra.sty v1.26:
an extension to the glossaries package}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\url{http://www.dickimaw-books.com/}}
- \date{2017-11-24}
+ \date{2018-01-05}
\maketitle
\begin{abstract}
@@ -1273,6 +1273,15 @@ accompanying sample file \texttt{sample-indexhook.tex},
which uses this hook to determine which entries haven't been
indexed.)
+There's also a new hook (from v1.26) that's used immediately
+before the options are set by the \cs{gls}-like and
+\cs{glstext}-like commands:
+\begin{definition}[\DescribeMacro\glslinkpresetkeys]
+\cs{glslinkpresetkeys}
+\end{definition}
+(The base package provides \ics{glslinkpostsetkeys} that's
+used immediately after the options are set.)
+
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
@@ -3032,7 +3041,7 @@ For example:
\end{verbatim}
The \glostyle{list} styles use
-\begin{definition}[\DescribeMacro\glsxtrprelocation]
+\begin{definition}[\DescribeMacro\glslistprelocation]
\cs{glslistprelocation}
\end{definition}
(which defaults to \cs{glsxtrprelocation}) for top-level items and
@@ -5761,6 +5770,15 @@ have the \catattr{entrycount} attribute set and
where the previous usage count for that entry is less than or
equal to the value of that attribute.
+\item[\catattrdef{linkcount}] This attribute is set to
+\texttt{true} by \ics{GlsXtrEnableLinkCounting} (see
+\sectionref{sec:linkcount}).
+
+\item[\catattrdef{linkcountmaster}] This attribute is set to
+the name of the master counter by \ics{GlsXtrEnableLinkCounting}
+if the optional argument is provided (see
+\sectionref{sec:linkcount}).
+
\item[\catattrdef{glossdesc}] The \ics{glossentrydesc} command
(used in the predefined glossary styles) is modified by
\styfmt{glossaries-extra} to check for this attribute.
@@ -6054,7 +6072,39 @@ glossaries using:
where \meta{glossary-labels} is a comma-separated list of glossary
labels.
-\chapter{Entry Counting}
+\chapter{Counting References}
+\label{sec:countref}
+
+There are three basic ways of counting entry references:
+\begin{enumerate}
+\item Counting the total number of times \cs{glsunset} is used
+(\cs{glsreset} resets the count and is best avoided).
+This is provided by the base \styfmt{glossaries} package and is
+intended for documents where the term should be displayed
+differently if it's only been used a certain number of times.
+The information has to be written to the \texttt{.aux} file
+so that it's available on the next \LaTeX\ run.
+
+This method is extended by \styfmt{glossaries-extra} and is
+described in \sectionref{sec:entrycount}.
+
+\item Counting the total number of records. This method is
+only available with \gls{bib2gls} and is intended
+for documents where the term should be displayed differently
+if it's only been recorded (indexed) a certain number of times.
+See \sectionref{sec:recordcount} for further details.
+
+\item Counting the number of times the \cs{gls}-like or
+\cs{glstext}-like commands are used. (That is, those commands
+that internally use \cs{@gls@link}.) Unlike the other two methods,
+this just provides a running total rather than the total from the
+previous \LaTeX\ run. This method is intended to make it more
+convenient to work with hooks like \cs{glslinkcheckfirsthyperhook},
+\cs{glslinkpostsetkeys} or \cs{glslinkpresetkeys}.
+See \sectionref{sec:linkcount} for further details.
+\end{enumerate}
+
+\section{Entry Counting (First Use Flag)}
\label{sec:entrycount}
As mentioned in \sectionref{sec:entrycountmods},
@@ -6079,9 +6129,11 @@ the \catattr{entrycount} attribute. (With \styfmt{glossaries},
commands like \ics{cgls} will generate a warning if
\cs{glsenableentrycount} hasn't been used.) The abbreviation
shortcut \ics{ab} uses \cs{cgls} (see
-\sectionref{sec:abbrshortcuts}) unlike the acronym shortcut \ics{ac}
-which uses \cs{gls} (except when it's defined through
-\pkgopt[ac]{shortcuts}).
+\sectionref{sec:abbrshortcuts}). The acronym shortcut
+\ics{ac} uses \cs{cgls} if it's been defined with
+\pkgopt[ac]{shortcuts} (or \pkgopt[all]{shortcuts})
+but uses \cs{gls} if it's been defined with
+\pkgopt[acronyms]{shortcuts} (or \pkgopt[acro]{shortcuts}).
All upper case versions (not provided by \styfmt{glossaries}) are
also available:
@@ -6407,6 +6459,171 @@ applies. If the first instance of \cs{gls} occurs at the top of the
page within a paragraph that started on the previous page, then
the count will continue from the previous page.
+\section{Link Counting}
+\label{sec:linkcount}
+
+As from version 1.26, an alternative method of entry counting
+is to count the number of times the \cs{gls}-like or
+\cs{glstext}-like commands are used. (The \qt{link} in this method's
+name refers to the use of the internal command \cs{@gls@link}
+not to \cs{hyperlink} although \cs{@gls@link} may use
+\cs{hyperlink} when displaying the \gls{linktext}.)
+
+To enable link counting use the preamble-only command:
+\begin{definition}[\DescribeMacro\GlsXtrEnableLinkCounting]
+\cs{GlsXtrEnableLinkCounting}\oarg{master counter}\marg{categories}
+\end{definition}
+where \meta{categories} is a list of category labels. The optional
+argument \meta{master counter} may be used to identify a master
+counter (which must be defined). If present, the associated
+link counter will be reset when the master counter is incremented.
+This command automatically sets the \catattr{linkcount} attribute
+for the given categories. If the optional argument is
+present, it also sets the \catattr{linkcountmaster} attribute.
+
+When enabled, commands like \cs{gls} and \cs{glstext}
+increment the associated counter using
+\begin{definition}[\DescribeMacro\glsxtrinclinkcounter]
+\cs{glsxtrinclinkcounter}\marg{counter name}
+\end{definition}
+This just does
+\texttt{\cs{stepcounter}\marg{counter name}} by default but if you
+need \cs{refstepcounter} instead, just redefine this command:
+\begin{verbatim}
+\renewcommand*{\glsxtrinclinkcounter}[1]{\refstepcounter{#1}}
+\end{verbatim}
+
+You can access the internal count register using
+\begin{definition}[\DescribeMacro\GlsXtrLinkCounterValue]
+\cs{GlsXtrLinkCounterValue}\marg{label}
+\end{definition}
+where \meta{label} is the entry's label. This will expand
+to 0 if the counter hasn't been defined.
+
+It's also possible to access the display value
+(\cs{the}\meta{counter}) using
+\begin{definition}[\DescribeMacro\GlsXtrTheLinkCounter]
+\cs{GlsXtrTheLinkCounter}\marg{counter}
+\end{definition}
+(This will expand to 0 if the counter hasn't been defined.)
+
+\begin{important}
+In order to conserve resources, the counter is only defined
+when it first needs to be incremented so terms that have
+been defined but haven't been used in the document
+won't have the associated count register allocated.
+\end{important}
+
+You can test if the counter has been defined using:
+\begin{definition}[\DescribeMacro\GlsXtrIfLinkCounterDef]
+\cs{GlsXtrIfLinkCounterDef}\marg{label}\marg{true}\marg{false}
+\end{definition}
+where \meta{label} is the entry's label.
+
+The counter name can be obtained using
+\begin{definition}[\DescribeMacro\GlsXtrLinkCounterName]
+\cs{GlsXtrLinkCounterName}\marg{label}
+\end{definition}
+This simply expands to the counter name associated with the
+entry given by \meta{label} without any check for
+existence. For example, to change the display command
+(\cs{the}\meta{counter}) using \sty{etoolbox}:
+\begin{verbatim}
+\csdef{the\GlsXtrLinkCounterName{duck}}{\Roman{\GlsXtrLinkCounterName{duck}}}
+\end{verbatim}
+This is useful if you just want to change the display for
+specific entries but isn't convenient if you want to change the
+display for all entries. Instead, it's simpler to redefine
+\cs{GlsXtrTheLinkCounter}. For example:
+\begin{verbatim}
+\renewcommand*{\GlsXtrTheLinkCounter}[1]{%
+ \GlsXtrIfLinkCounterDef{#1}%
+ {\Roman{\GlsXtrLinkCounterName{#1}}}%
+ {0}%
+}
+\end{verbatim}
+In both cases, the redefinition should be implemented
+after \cs{GlsXtrEnableLinkCounting}.
+
+Here's an example document that uses link counting to disable
+the hyperlink after the first reference. This redefines
+\ics{glslinkpresetkeys} (which is used by both \cs{gls}
+and \cs{glstext}) instead of
+\cs{glslinkcheckfirsthyperhook} (which is used by \cs{gls}
+but not by \cs{glstext}).
+
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage{glossaries-extra}
+
+\makeglossaries
+
+\renewcommand*{\glslinkpresetkeys}{%
+ \ifnum\GlsXtrLinkCounterValue{\glslabel}>1
+ \setkeys{glslink}{hyper=false}%
+ \fi
+}
+
+\GlsXtrEnableLinkCounting{general}
+
+\newglossaryentry{sample1}{name={sample1},description={an example}}
+\newglossaryentry{sample2}{name={sample2},description={another example}}
+
+\newabbreviation{ex}{ex}{example}
+
+\begin{document}
+
+\section{Sample Section}
+
+\Gls{sample1}, \gls{sample2} and \gls{ex}.
+\Glstext{sample1} and \gls{ex} again.
+
+\section{Another Sample Section}
+
+\Gls{sample1}, \gls{sample2} and \gls{ex}.
+
+\printglossaries
+
+\end{document}
+\end{verbatim}
+The use of \ics{glslinkpresetkeys}
+means that the options can override this. For example
+\begin{verbatim}
+\gls[hyper=true]{sample1}
+\end{verbatim}
+will override the \texttt{hyper=false} setting in
+\ics{glslinkpresetkeys}. If \ics{glslinkpostsetkeys} is used
+instead, the \texttt{hyper=false} setting will override
+the setting provided in the optional argument.
+
+The \category{abbreviation} category doesn't have the
+\catattr{linkcount} attribute set (since it's not
+listed in the argument of \cs{GlsXtrEnableLinkCounting}). This means that
+\cs{GlsXtrLinkCounterValue}
+always expands to 0 for the abbreviation (\texttt{ex}), so the
+inequality test
+\begin{verbatim}
+\ifnum\GlsXtrLinkCounterValue{\glslabel}>1
+\end{verbatim}
+will always be false. This means that the abbreviation won't
+have \texttt{hyper=false} applied. If the test is changed to
+\begin{verbatim}
+\ifnum\GlsXtrLinkCounterValue{\glslabel}=1
+\else
+ \setkeys{glslink}{hyper=false}%
+\fi
+\end{verbatim}
+Then the abbreviation will always have \texttt{hyper=false}
+applied.
+
+To reset the counter every section use the optional argument to set
+the master counter:
+\begin{verbatim}
+\GlsXtrEnableLinkCounting[section]{general}
+\end{verbatim}
+
\chapter{Auto-Indexing}
\label{sec:autoindex}
@@ -6711,6 +6928,10 @@ There are some new commands and options added to
\styfmt{glossaries-extra} to help assist the integration of
\gls{bib2gls} into the document build process.
+This chapter just provides a general overview of \gls{bib2gls}.
+The full details and some sample documents are provided
+in the \gls{bib2gls} \href{http://mirrors.ctan.org/support/bib2gls/bib2gls.pdf}{manual}.
+
An example of the contents of \texttt{.bib} file that stores
glossary entries that can be extracted with \gls{bib2gls}:
\begin{verbatim}
@@ -7037,14 +7258,14 @@ if you are using \XeLaTeX\ or \LuaLaTeX:
\cs{GlsXtrLoadResources}[
src=terms, % entries in terms.bib
sort=custom, % custom sort rule
- sort-rule={% required with sort=custom
+ sort-rule=\{% required with sort=custom
< \ae;\AE\ < a;\'a;\aa;\"a,\"A;\'A;\AA;\"A < b,B
< c;\'c,C;\'C < d,D < e;\'e,E;\'E < f,F < g,G
< h,H < i;\'i,I;\'I < j,J < l;\l,L;\L < m,M < n,N
< o;\"o;\o,O;\"O;\O\ < p,P < q,Q < r,R < s;\'s,S;\'S
< t,T < u;\'u,U;\'U < v,V < w,W < x,X < y,Y <
z;\.z,Z;\.Z
- }
+ \}
]
\end{alltt}
Remember that if you are using \sty{inputenc} then extended
@@ -7053,24 +7274,30 @@ written to the \texttt{.aux} file. So with PDF\LaTeX\ the
above would have to be changed to protect against expansion.
Some of the options, including \texttt{sort-rule},
may have Unicode characters indicated in the format
-\cs{u}\meta{hex} \emph{in the \texttt{.aux} file}. \gls{bib2gls}
+\cs{u}\meta{hex} (or \cs{u}~\meta{hex}) \textbf{in the \texttt{.aux} file}. \gls{bib2gls}
will recognise this format as indicating the character
given by the hexadecimal value \meta{hex}. The \cs{u} also needs
protection from expansion, so with a non-Unicode aware
-engine the above needs to be written as:
+engine, the character \ae\ needs to be written as
+\texttt{\cs{string}\cs{u}E6} and so on. This is quite cumbersome,
+but you can use the shortcut \texttt{\ics{glshex} E6} instead, so
+the above needs to be written as:
\begin{alltt}
\cs{GlsXtrLoadResources}[
src=terms, % entries in terms.bib
sort=custom, % custom sort rule
- sort-rule={% required with sort=custom
- < \cs{string}\cs{u}E6;\cs{string}\cs{u}C6 < a;\cs{string}\cs{u}E1;\cs{string}\cs{u}E5,\cs{string}\cs{u}E4,A;\cs{string}\cs{u}C1;\cs{string}\cs{u}C5;\cs{string}\cs{u}C4 < b,B
- < c;\cs{string}\cs{u}0107,C;\cs{string}\cs{u}0106 < d,D < e;\cs{string}\cs{u}E9,E;\cs{string}\cs{u}C9 < f,F < g,G
- < h,H < i;\cs{string}\cs{u}ED,I;\cs{string}\cs{u}CD < j,J < l;\cs{string}\cs{u}0142,L;\cs{string}\cs{u}0141 < m,M < n,N
- < o;\cs{string}\cs{u}F6;\cs{string}\cs{u}F8,O;\cs{string}\cs{u}D6;\cs{string}\cs{u}D8 < p,P < q,Q < r,R < s;\cs{string}\cs{u}013F,S;\cs{string}\cs{u}015A
- < t,T < u;\cs{string}\cs{u}FA,U;\cs{string}\cs{u}DA < v,V < w,W < x,X < y,Y <
- z;\cs{string}\cs{u}017C,Z;\cs{string}\cs{u}017B
- }
-]
+ sort-rule=\{% required with sort=custom
+ < \cs{glshex} E6;\cs{glshex} C6
+ < a;\cs{glshex} E1;\cs{glshex} E5,\cs{glshex} E4,A;\cs{glshex} C1;\cs{glshex} C5;\cs{glshex} C4
+ < b,B < c;\cs{glshex} 0107,C;\cs{glshex} 0106 < d,D
+ < e;\cs{glshex} E9,E;\cs{glshex} C9 < f,F < g,G
+ < h,H < i;\cs{glshex} ED,I;\cs{glshex} CD < j,J
+ < l;\cs{glshex} 0142,L;\cs{glshex} 0141 < m,M < n,N
+ < o;\cs{glshex} F6;\cs{glshex} F8,O;\cs{glshex} D6;\cs{glshex} D8
+ < p,P < q,Q < r,R < s;\cs{glshex} 013F,S;\cs{glshex} 015A
+ < t,T < u;\cs{glshex} FA,U;\cs{glshex} DA < v,V < w,W < x,X < y,Y
+ < z;\cs{glshex} 017C,Z;\cs{glshex} 017B
+ \}]
\end{alltt}
\section{Supplementary Commands}
@@ -7084,7 +7311,7 @@ for use with \gls{bib2gls}.
This is just defined as \verb|\string\u|, which is required
when you need to indicate a Unicode character in the form
\cs{u}\meta{hex} in some of
-the resource options (as described above).
+the resource options (as illustrated above).
The information provided with \cs{GlsXtrLoadResources}
is written to the \texttt{.aux} file using
@@ -7103,7 +7330,7 @@ short commands for convenience. For example, with:
\begin{verbatim}
\renewcommand{\glsxtrresourceinit}{\let\u\glshex}
\end{verbatim}
-you can just use, for example, \verb|\uE6| instead of
+you can just use, for example, \verb|\u E6| instead of
\verb|\string\uE6| in the custom rule. This redefinition of \cs{u}
is scoped so its original definition is restored after the write operation.
@@ -7145,14 +7372,14 @@ to define custom commands that set the prefix. For example:
\newcommand*{\sym}[2][]{\gls[#1]{sym.#2}}
\end{verbatim}
The problem with this is that the custom command \cs{sym}
-does allow for modifiers (such as \cs{gls*} or \cs{gls+}).
+doesn't allow for modifiers (such as \cs{gls*} or \cs{gls+}).
Instead you can use:
\begin{definition}[\DescribeMacro\glsxtrnewgls]
\cs{glsxtrnewgls}\oarg{default options}\marg{prefix}\marg{cs}
\end{definition}
which defines the command \meta{cs} that behaves like
\begin{alltt}
-\cs{gls}\meta{modifier}[\meta{default options},options]\{\meta{prefix}\meta{label}\}\oarg{insert}
+\cs{gls}\meta{modifier}[\meta{default options},\meta{options}]\{\meta{prefix}\meta{label}\}\oarg{insert}
\end{alltt}
For example:
\begin{verbatim}
@@ -7202,6 +7429,7 @@ options}\marg{prefix}\marg{\cs{rGLS}-like cs}\marg{\cs{rGLSpl}-like cs}
\end{definition}
\section{Record Counting}
+\label{sec:recordcount}
As from version 1.1 of \gls{bib2gls}, you can save the total
record count for each entry by invoking \gls{bib2gls}
@@ -7507,9 +7735,9 @@ command to an argument:
\end{definition}
This effectively does
\begin{alltt}
-\cs{glslink}[\meta{default-options},\meta{options}]\marg{label}\{\cs{glsxtrfmtdisplay}\marg{text}\{\}\}
+\cs{glslink}[\meta{default-options},\meta{options}]\marg{label}\{\cs{glsxtrfmtdisplay}\marg{cs name}\marg{text}\{\}\}
\end{alltt}
-where \meta{cs} is the command obtained from the control
+where \meta{cs name} is the control
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.
@@ -7692,7 +7920,9 @@ package provides a simpler version:
\begin{definition}[\DescribeMacro\glsxtrifhasfield]
\cs{glsxtrifhasfield}\marg{field}\marg{label}\marg{true}\marg{false}
\end{definition}
-(New to v1.19.)
+(New to v1.19.) Note that in this case the \meta{field} must be the
+\emph{internal} field label (for example, \texttt{useri} rather than
+\texttt{user1}).
Unlike \cs{ifglshasfield}, this version doesn't complain if the
entry (given by \meta{label}) or the field don't exist and
will simply do \meta{false}. If the field does exist for the given
@@ -7709,6 +7939,11 @@ The starred version
\end{definition}
omits the implicit grouping.
+\begin{important}
+Be careful of keys that use \cs{relax} as the default value
+(such as the \gloskey{symbol}). Use \cs{ifglshassymbol} instead.
+\end{important}
+
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:
@@ -8657,16 +8892,22 @@ entries to the index (in addition to the glossary \gls{locationlist}).
value of the \gloskey{name} key.
\item[sample-entrycount.tex] Enable entry-use counting (only index
-if used more than $n$ times).
+if used more than $n$ times, see \sectionref{sec:entrycount}).
-\item[sample-unitentrycount.tex] Enable use of per-unit entry-use counting.
-
-\item[sample-pages.tex] Insert \qt{page} or \qt{pages} before the
-location list.
+\item[sample-unitentrycount.tex] Enable use of per-unit entry-use counting
+(\sectionref{sec:entrycount}).
\item[sample-onelink.tex] Using the per-unit entry counting
+(\sectionref{sec:entrycount})
to only have one hyperlink per entry per page.
+\item[sample-linkcount.tex] Using link counting
+(\sectionref{sec:linkcount})
+to only have one hyperlink per entry.
+
+\item[sample-pages.tex] Insert \qt{page} or \qt{pages} before the
+location list.
+
\item[sample-altmodifier.tex] Set the default options for
commands like \cs{gls} and add an alternative modifier.