summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex232
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}