diff options
author | Karl Berry <karl@freefriends.org> | 2018-01-05 21:49:40 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-01-05 21:49:40 +0000 |
commit | 5add5510b8b8121f5575f0c8cc8397a36abb3eab (patch) | |
tree | 73404b86be8e89ade21b16da0d34c5fec5c3f77f /Master/texmf-dist/doc/latex/glossaries-extra/glossaries-extra-manual.tex | |
parent | fe0e333e467cf6e0d1a533da3ff7caa679aeb1dc (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.tex | 305 |
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. |