diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex | 232 |
1 files changed, 229 insertions, 3 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex index c1df666fc19..0bda9eba4e6 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex @@ -367,11 +367,11 @@ and~\hyperlink{option#2}{#2}} \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{User Manual for glossaries.sty v4.13} + \title{User Manual for glossaries.sty v4.14} \author{Nicola L.C. Talbot\\% \url{http://www.dickimaw-books.com/}} - \date{2015-02-03} + \date{2015-02-28} \maketitle \begin{abstract} @@ -433,7 +433,7 @@ letter}{mfirstuc-manual}. \item[\url{glossaries-code.pdf}] Advanced users wishing to know more about the inner workings of all the packages provided in the \styfmt{glossaries} bundle should read -\qt{Documented Code for glossaries v4.13}. +\qt{Documented Code for glossaries v4.14}. This includes the documented code for the \sty{mfirstuc} package. \item[INSTALL] Installation instructions. @@ -1264,6 +1264,10 @@ about the \styfmt{glossaries-accsupp} package can be found in \exitem{-ignored} This document defines an ignored glossary for common terms that don't need a definition. +\exitem{-entrycount} This document uses \ics{glsenableentrycount} +and \ics{cgls} (described in \sectionref{sec:enableentrycount}) +so that acronyms only used once don't appear in the list of +acronyms. \end{samplelist} \section{Dummy Entries for Testing} @@ -8026,6 +8030,228 @@ The \sty{amsmath} environments, such as \env{align}, also process their contents multiple times, but the \styfmt{glossaries} package now checks for this. +\section{Counting the Number of Times an Entry has been Used (First Use +Flag Unset)} +\label{sec:enableentrycount} + +As from version 4.14, it's now possible to keep track of how many +times an entry is used. That is, how many times the \firstuseflag\ +is unset. + +\begin{important} +This function is disabled by default as it adds extra +overhead to the document build time and also switches +\ics{newglossaryentry} (and therefore \ics{newacronym}) into +a~preamble-only command. +\end{important} + +To enable this function, use +\begin{definition}[\DescribeMacro\glsenableentrycount] +\cs{glsenableentrycount} +\end{definition} +before defining your entries. This adds two extra (internal) fields +to entries: \texttt{currcount} and \texttt{prevcount}. + +The \texttt{currcount} field keeps track of how many times +\cs{glsunset} is used within the document. A~local unset (using +\cs{glslocalunset}) performs a~local rather than global increment to +\texttt{currcount}. Remember that not all commands use +\cs{glsunset}. Only the \glslike\ commands do this. The reset +commands \cs{glsreset} and \cs{glslocalreset} reset this field back +to zero (where \cs{glslocalreset} performs a~local change). + +The \texttt{prevcount} field stores the final value of the +\texttt{currcount} field \emph{from the previous run}. This value is +read from the \texttt{.aux} file at the beginning of the +\env{document} environment. + +You can access these fields using +\begin{definition}[\DescribeMacro\glsentrycurrcount] +\cs{glsentrycurrcount}\marg{label} +\end{definition} +for the \texttt{currcount} field, and +\begin{definition}[\DescribeMacro\glsentryprevcount] +\cs{glsentryprevcount}\marg{label} +\end{definition} +for the \texttt{prevcount} field. \textbf{These commands are +only defined if you have used \cs{glsenableentrycount}.} + +For example: +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\makeglossaries + +\glsenableentrycount + +\newglossaryentry{apple}{name=apple,description={a fruit}} + +\begin{document} +Total usage on previous run: \glsentryprevcount{apple}. + +\gls{apple}. \gls{apple}. \glsadd{apple}\glsentrytext{apple}. +\glslink{apple}{apple}. \glsdisp{apple}{apple}. \Gls{apple}. + +Number of times apple has been used: \glsentrycurrcount{apple}. +\end{document} +\end{verbatim} +On the first \LaTeX\ run, \verb|\glsentryprevcount{apple}| +produces~0. At the end of the document, +\verb|\glsentrycurrcount{apple}| produces~4. This is because +the only commands that have incremented the entry count are those +that use \cs{glsunset}. That is: \cs{gls}, \cs{glsdisp} and +\cs{Gls}. The other commands used in the above example, \cs{glsadd}, +\cs{glsentrytext} and \cs{glslink}, don't use \cs{glsunset} so they +don't increment the entry count. On the \emph{next} \LaTeX\ run, +\verb|\glsentryprevcount{apple}| now produces~4 as that was the +value of the \texttt{currcount} field for the \texttt{apple} entry +at the end of the document on the previous run. + +When you enable the entry count using \cs{glsenableentrycount}, you +also enable the following commands: +\begin{definition}[\DescribeMacro\cgls] +\cs{cgls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(no case-change, singular) +\begin{definition}[\DescribeMacro\cglspl] +\cs{cglspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(no case-change, plural) +\begin{definition}[\DescribeMacro\cGls] +\cs{cGls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(first letter uppercase, singular), and +\begin{definition}[\DescribeMacro\cGlspl] +\cs{cGlspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +(first letter uppercase, plural). +These all have plus and starred variants like the analogous +\cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl} commands. + +If you don't use \cs{glsenableentrycount}, these commands behave +like \cs{gls}, \cs{glspl}, \cs{Gls} and \cs{Glspl}, +respectively, only there will be a warning that you haven't enabled +entry counting. If you have enabled entry counting with +\cs{glsenableentrycount} then these commands test if +\cs{glsentryprevcount}\marg{label} equals~1. If it doesn't then the +analogous \cs{gls} etc will be used. If it does, then the first optional +argument will be ignored and +\begin{alltt} +\meta{cs format}\marg{label}\marg{insert}\cs{glsunset}\marg{label} +\end{alltt} +will be performed, where \meta{cs format} is a command that takes +two arguments. The command used depends whether you have used +\cs{cgls}, \cs{cglspl}, \cs{cGls} or \cs{cGlspl}. + +\begin{definition}[\DescribeMacro\cglsformat] +\cs{cglsformat}\marg{label}\marg{insert} +\end{definition} +This command is used by \cs{cgls} and defaults to +\begin{alltt} +\cs{glsentrylong}\marg{label}\meta{insert} +\end{alltt} +if the entry given by +\meta{label} has a~long form or +\begin{alltt} +\cs{glsentryfirst}\marg{label}\meta{insert} +\end{alltt} +otherwise. + +\begin{definition}[\DescribeMacro\cglsplformat] +\cs{cglsplformat}\marg{label}\marg{insert} +\end{definition} +This command is used by \cs{cglspl} and defaults to +\begin{alltt} +\cs{glsentrylongpl}\marg{label}\meta{insert} +\end{alltt} +if the entry given by +\meta{label} has a~long form or +\begin{alltt} +\cs{glsentryfirstplural}\marg{label}\meta{insert} +\end{alltt} +otherwise. + +\begin{definition}[\DescribeMacro\cGlsformat] +\cs{cGlsformat}\marg{label}\marg{insert} +\end{definition} +This command is used by \cs{cGls} and defaults to +\begin{alltt} +\cs{Glsentrylong}\marg{label}\meta{insert} +\end{alltt} +if the entry given by \meta{label} has a~long form or +\begin{alltt} +\cs{Glsentryfirst}\marg{label}\meta{insert} +\end{alltt} +otherwise. + +\begin{definition}[\DescribeMacro\cGlsplformat] +\cs{cGlsplformat}\marg{label}\marg{insert} +\end{definition} +This command is used by \cs{cGlspl} and defaults to +\begin{alltt} +\cs{Glsentrylongpl}\marg{label}\meta{insert} +\end{alltt} +if the entry given by \meta{label} has a~long form or +\begin{alltt} +\cs{Glsentryfirstplural}\marg{label}\meta{insert} +otherwise. +\end{alltt} + +This means that if the previous count for the given entry was~1, the +entry won't be hyperlinked with the \cs{cgls}-like commands and they +won't add a~line to the external glossary file. If you haven't used +any of the other commands that add information to glossary file +(such as \cs{glsadd} or the \glstextlike\ commands) then the entry +won't appear in the glossary. + +Remember that since these commands use \cs{glsentryprevcount} you +need to run \LaTeX\ twice to ensure they work correctly. The +document build order is now (at least): \texttt{(pdf)latex}, +\texttt{(pdf)latex}, \texttt{makeglossaries}, \texttt{(pdf)latex}. + +\begin{example}{Don't index entries that are only used once}{sec:entrycount} +In this example, the acronyms that have only been used once (on the previous run) +only have their long form shown with \cs{cgls}. +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage[nomain,acronym]{glossaries} +\makeglossaries + +\glsenableentrycount + +\setacronymstyle{long-short} + +\newacronym{html}{HTML}{hypertext markup language} +\newacronym{css}{CSS}{cascading style sheets} +\newacronym{xml}{XML}{extensible markup language} +\newacronym{sql}{SQL}{structured query language} +\newacronym{rdbms}{RDBMS}{relational database management system} +\newacronym{rdsms}{RDSMS}{relational data stream management system} + +\begin{document} +These entries are only used once: \cgls{sql}, \cgls{rdbms}, +\cgls{xml}. These entries are used multiple times: +\cgls{html}, \cgls{html}, \cgls{css}, \cgls{css}, \cgls{css}, +\cgls{rdsms}, \cgls{rdsms}. + +\printglossaries +\end{document} +\end{verbatim} +After a complete document build (\texttt{latex}, \texttt{latex}, +\texttt{makeglossaries}, \texttt{latex}) the list of acronyms only +includes the entries HTML, CSS and RDSMS. The entries SQL, RDBMS and +XML +only have their long forms displayed and don't have a~hyperlink. +\end{example} + +Remember that if you don't like typing \cs{cgls} you can create a +synonym. For example +\begin{verbatim} +\let\ac\cgls +\end{verbatim} + \chapter{Glossary Styles} \label{sec:styles} |