diff options
author | Karl Berry <karl@freefriends.org> | 2013-12-06 22:12:47 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-12-06 22:12:47 +0000 |
commit | cfbdc127e742f1a0758482a6e7c5f00985127ff6 (patch) | |
tree | a4c682376d022ca5c3c73595a489e32f26c66948 /Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex | |
parent | 7f304fc721af7e006a9209f30840ad96bfab1e9f (diff) |
glossaries (6dec13)
git-svn-id: svn://tug.org/texlive/trunk@32341 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex | 1678 |
1 files changed, 1096 insertions, 582 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex index 9ae13e07824..3cb0f0ab9b9 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex @@ -5,14 +5,13 @@ \usepackage{array} \usepackage{alltt} \usepackage{pifont} -\usepackage[utf8]{inputenc} -\usepackage[T1]{fontenc} -\usepackage{lmodern} -\usepackage{fourier} \ifpdf +\usepackage{lmodern} \usepackage{mathpazo} \usepackage[scaled=.88]{helvet} \usepackage{courier} +\else + \newcommand{\grimace}{{\fontencoding {U}\fontfamily{futs}\selectfont \char77}} \fi \usepackage[colorlinks, bookmarks, @@ -257,6 +256,8 @@ user2={sanitization\protect\iterm{sanitize}}% \newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\ttfamily#1}|main}} +\newcommand*{\acrstyle}[1]{\textsf{#1}\index{acronym styles:>#1={\protect\ttfamily#1}|main}} + \newcounter{sample} \newcommand{\exitem}[2][sample]{% \item[\texttt{#1#2.tex}]% @@ -279,15 +280,15 @@ user2={sanitization\protect\iterm{sanitize}}% \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{User Manual for glossaries.sty v4.01} + \title{User Manual for glossaries.sty v4.02} \author{Nicola L.C. Talbot\\% \url{http://www.dickimaw-books.com/}} - \date{2013-11-16} + \date{2013-12-05} \maketitle \begin{important} -Documents have varied styles when it comes to presenting glossaries +Documents have various styles when it comes to presenting glossaries or lists of terms or notation. People have their own preferences and to a large extent this is determined by the kind of information that needs to go in the glossary. They may just have symbols with @@ -329,7 +330,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.01}. +\qt{Documented Code for glossaries v4.02}. This includes the documented code for the \sty{mfirstuc} package. \item[INSTALL] Installation instructions. @@ -354,7 +355,7 @@ rather than \app{latex} (DVI format) as \appfmt{pdflatex} deals with hyperlinks much better. If you use the DVI format, you will encounter problems where you have long hyperlinks or hyperlinks in subscripts or superscripts. This is an issue with the DVI format not -with \sty{glossaries}. +with \styfmt{glossaries}. \end{important} Other documents that describe using the \styfmt{glossaries} package include: @@ -565,6 +566,27 @@ latex sampleDesc latex sampleDesc \end{prompt} +\exitem{CustomAcr} This document has some sample acronyms with a +custom acronym style. It also adds the glossary to the table of +contents, so an extra run through \LaTeX\ is required: +\begin{prompt} +latex sampleCustomAcr +makeglossaries sampleCustomAcr +latex sampleCustomAcr +latex sampleCustomAcr +\end{prompt} + +\exitem{FnAcrDesc} This is similar to \samplefile{AcrDesc}, except that it +uses the \acrstyle{footnote-sc-desc} style. As with the previous example, +the glossary is added to the table of contents, so an extra run through +\LaTeX\ is required: +\begin{prompt} +latex sampleFnAcrDesc +makeglossaries sampleFnAcrDesc +latex sampleFnAcrDesc +latex sampleFnAcrDesc +\end{prompt} + \exitem{-FnDesc} This example defines a custom display format that puts the description in a footnote on first use. @@ -916,7 +938,7 @@ expansions with \cs{glsnoexpandfields}. If you use an accented (or other expandable) character at the start of an entry name, you must place it in a group, or it will cause -a problem for commands that convert the first letter to uppercase +a problem for commands that convert the first letter to upper case (e.g.\ \ics{Gls}) due to expansion issues. For example: \begin{verbatim} \newglossaryentry{elite}{name={{é}lite}, @@ -1034,7 +1056,7 @@ this option. Due to the varied nature of glossaries, it's likely that the predefined translations may not be appropriate. If you are using the -\sty{babel} package and the \sty{glossaries} package option \pkgopt[babel]{translate}, you need to be familiar with the advice given in +\sty{babel} package and the \styfmt{glossaries} package option \pkgopt[babel]{translate}, you need to be familiar with the advice given in \urlref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}{changing the words babel uses}. If you are using the \sty{translator} package, then you can provide your own dictionary with the necessary @@ -1297,7 +1319,7 @@ resulting file onto the man path. Alternatively do \begin{important} When upgrading the \styfmt{glossaries} package, make sure you also upgrade your version of \gls{makeglossaries}. The current version is -2.09. +2.10. \end{important} \subsection{Using xindy explicitly} @@ -1482,7 +1504,7 @@ options. You may omit the \texttt{=true} for boolean options. (For example, \pkgopt{acronym} is equivalent to \pkgopt[true]{acronym}). \begin{important} -Note that \meta{key}=\meta{value} options can't be passed via the +Note that \meta{key}=\meta{value} package options can't be passed via the document class options. (This includes options where the \meta{value} part may be omitted, such as \pkgopt{acronym}.) This is a general limitation not restricted to the \styfmt{glossaries} @@ -1502,9 +1524,10 @@ glossary and associated \texttt{.glo} file, if unrequired. Note that if you use this option, you must create another glossary in which to put all your entries (either via the \pkgopt{acronym} (or \pkgopt{acronyms}) package option described in -\sectionref{sec:pkgopts-acronym} or via the \pkgopt{symbols} or -\pkgopt{numbers} options described in \sectionref{sec:pkgopts-other} -or via \ics{newglossary} described in \sectionref{sec:newglossary}). +\sectionref{sec:pkgopts-acronym} or via the \pkgopt{symbols}, +\pkgopt{numbers} or \pkgopt{index} options described in +\sectionref{sec:pkgopts-other} or via \ics{newglossary} described in +\sectionref{sec:newglossary}). \begin{important} If you don't use the main glossary and you don't use this option, @@ -1536,8 +1559,10 @@ expanded, you need to switch off the sanitization. For example, suppose you do: \begin{verbatim} \newcommand{\mysortvalue}{AAA} -\newglossaryentry{sample}{name={sample},sort={\mysortvalue}, - description={an example}} +\newglossaryentry{sample}{% + name={sample}, + sort={\mysortvalue}, + description={an example}} \end{verbatim} and you actually want \cs{mysortvalue} expanded, so that the entry is sorted according to \texttt{AAA}, then use the package option @@ -1632,11 +1657,11 @@ subsequent uses). In this case, you can use \pkgopt[false]{hyperfirst} and apply \cs{glsunsetall} to all the regular (non-acronym) glossaries. For example: \begin{verbatim} -\usepackage[acronym,hyperfirst=false]{glossaries} -% acronym and glossary entry definitions + \usepackage[acronym,hyperfirst=false]{glossaries} + % acronym and glossary entry definitions -% at the end of the preamble -\glsunsetall[main] + % at the end of the preamble + \glsunsetall[main] \end{verbatim} \item[\pkgopt{nohypertypes}] Use this option if you have multiple @@ -1646,7 +1671,8 @@ be a comma-separated list of glossary types where \ics{gls} etc shouldn't have hyperlinks by default. Make sure you enclose the value in braces if it contains any commas. Example: \begin{verbatim} -\usepackage[acronym,nohypertypes={acronym,notation}]{glossaries} +\usepackage[acronym,nohypertypes={acronym,notation}] + {glossaries} \newglossary[nlg]{notation}{not}{ntn}{Notation} \end{verbatim} The values must be fully expanded, so \textbf{don't} try @@ -1765,27 +1791,36 @@ If \cls{memoir} has been loaded and \pkgopt{ucfirst} is set, then \item[\pkgopt{numberedsection}] The glossaries are placed in unnumbered sectional units by default, but this can be changed using \pkgopt{numberedsection}. This option can take -three possible values: \pkgoptval{false}{numberedsection} (no -number, i.e.\ use starred form), \pkgoptval{nolabel}{numberedsection} -(numbered, i.e.\ unstarred form, but not labelled) and -\pkgoptval{autolabel}{numberedsection} (numbered with automatic -labelling). If \pkgopt[autolabel]{numberedsection} is used, each -glossary is given a label that matches the glossary type, so the -main (default) glossary is labelled \texttt{main}, the list of -acronyms is labelled \texttt{acronym}\footnote{if the -\pkgopt{acronym} option is used, otherwise the list of -acronyms is the main glossary} and additional glossaries are labelled -using the value specified in the first mandatory argument to -\cs{newglossary}. For example, if you load \styfmt{glossaries} +one of the following values: +\begin{itemize} +\item \pkgoptval{false}{numberedsection}: no number, i.e.\ use starred form +of sectioning command (e.g.\ \cs{chapter*} or \cs{section*}); + +\item \pkgoptval{nolabel}{numberedsection}: +use a numbered section, i.e.\ the unstarred form of sectioning +command (e.g.\ \cs{chapter} or \cs{section}), but +the section not labelled; + +\item \pkgoptval{autolabel}{numberedsection}: numbered with automatic +labelling. Each glossary uses the unstarred form of a sectioning +command (e.g.\ \cs{chapter} or \cs{section}) and is assigned a label +(via \ics{label}). The label is formed from +\begin{definition}[\DescribeMacro{\glsautoprefix}] +\cs{glsautoprefix} \meta{type} +\end{definition} +where +\meta{type} is the label identifying that glossary. The default +value of \cs{glsautoprefix} is empty. For example, if you load \styfmt{glossaries} using: \begin{verbatim} -\usepackage[section,numberedsection=autolabel]{glossaries} +\usepackage[section,numberedsection=autolabel] + {glossaries} \end{verbatim} then each glossary will appear in a numbered section, and can be referenced using something like: \begin{verbatim} -The main glossary is in section~\ref{main} and the list of -acronyms is in section~\ref{acronym}. +The main glossary is in section~\ref{main} and +the list of acronyms is in section~\ref{acronym}. \end{verbatim} If you can't decide whether to have the acronyms in the main glossary or a separate list of acronyms, you can use @@ -1795,12 +1830,8 @@ if the \pkgopt{acronym} option is used. For example: \begin{verbatim} The list of acronyms is in section~\ref{\acronymtype}. \end{verbatim} - -As from version 1.14, you can add a prefix to the label by -redefining -\begin{definition}[\DescribeMacro{\glsautoprefix}] -\cs{glsautoprefix} -\end{definition} +You can redefine the prefix if the default label clashes with +another label in your document. For example: \begin{verbatim} \renewcommand*{\glsautoprefix}{glo:} @@ -1817,6 +1848,19 @@ The list of acronyms is in section~\ref{\glsautoprefix\acronymtype}. \end{verbatim} +\item \pkgoptval{nameref}{numberedsection}: this is like +\pkgoptval{autolabel}{numberedsection} but uses an unnumbered +sectioning command (e.g.\ \ics{chapter*} or \ics{section*}). It's +designed for use with the \sty{nameref} package. For example: +\begin{verbatim} +\usepackage{nameref} +\usepackage[numberedsection=nameref]{glossaries} +\end{verbatim} +Now \verb|\nameref{main}| will display the (TOC) section title +associated with the \texttt{main} glossary. As above, you can +redefine \cs{glsautoprefix} to provide a prefix for the label. +\end{itemize} + \end{description} \section{Glossary Appearance Options} @@ -2157,7 +2201,8 @@ This package option may additionally have a value that is a \meta{key}=\meta{value} comma-separated list to override the language and codepage. For example: \begin{verbatim} -\usepackage[xindy={language=english,codepage=utf8}]{glossaries} +\usepackage[xindy={language=english,codepage=utf8}] + {glossaries} \end{verbatim} You can also specify whether you want a number group in the glossary. This defaults to true, but can be suppressed. For example: @@ -2176,6 +2221,10 @@ supplied) and may be used as a document class option. The language and code page can be set via \ics{GlsSetXdyLanguage} and \ics{GlsSetXdyCodePage} (see \sectionref{sec:langenc}.) +\item[\pkgopt{xindynoglsnumbers}] This is equivalent to +\verb|xindy={glsnumbers=false}| and may be used as a document class +option. + \end{description} \section{Acronym Options} @@ -2229,8 +2278,10 @@ glossary to also contain a list of acronyms, you can do: No check is performed to determine if the listed glossaries exist, so you can add glossaries you haven't defined yet. For example: \begin{verbatim} -\usepackage[acronym,acronymlists={main,acronym2}]{glossaries} -\newglossary[alg2]{acronym2}{acr2}{acn2}{Statistical Acronyms} +\usepackage[acronym,acronymlists={main,acronym2}] + {glossaries} +\newglossary[alg2]{acronym2}{acr2}{acn2}% + {Statistical Acronyms} \end{verbatim} You can use \begin{definition}[\DescribeMacro\DeclareAcronymList] @@ -2239,7 +2290,7 @@ You can use instead of or in addition to the \pkgopt{acronymlists} option. This will add the glossaries given in \meta{list} to the list of glossaries that are identified as lists of acronyms. To replace the list of acronym lists -use with a new list use: +with a new list use: \begin{definition}[\DescribeMacro\SetAcronymLists] \cs{SetAcronymLists}\marg{list} \end{definition} @@ -2250,15 +2301,67 @@ of acronyms using: \cs{glsIfListOfAcronyms}\marg{label}\marg{true part}\marg{false part} \end{definition} +\item[\pkgopt{shortcuts}] This option provides shortcut commands +for acronyms. See \sectionref{sec:acronyms} for further details. +Alternatively you can use: +\begin{definition}[\DescribeMacro\DefineAcronymShortcuts] +\cs{DefineAcronymShortcuts} +\end{definition} +\end{description} + +\subsection{Deprecated Acronym Style Options} +\label{sec:pkgopts-old-acronym} + +The package options listed in this section are now deprecated but +are kept for backward-compatibility. Use \ics{setacronymstyle} +instead. See \sectionref{sec:acronyms} for further details. + +\begin{description} \item[\pkgopt{description}] This option changes the definition of -\ics{newacronym} to allow a description. This option may have no effect if -you define your own custom acronym style. See -\sectionref{sec:acronyms} for further details. +\ics{newacronym} to allow a description. +This option may be replaced by +\begin{verbatim} +\setacronymstyle{long-short-desc} +\end{verbatim} +or (with \pkgopt{smallcaps}) +\begin{verbatim} +\setacronymstyle{long-sc-short-desc} +\end{verbatim} +or (with \pkgopt{smaller}) +\begin{verbatim} +\setacronymstyle{long-sm-short-desc} +\end{verbatim} +or (with \pkgopt{footnote}) +\begin{verbatim} +\setacronymstyle{footnote-desc} +\end{verbatim} +or (with \pkgopt{footnote} and \pkgopt{smallcaps}) +\begin{verbatim} +\setacronymstyle{footnote-sc-desc} +\end{verbatim} +or (with \pkgopt{footnote} and \pkgopt{smaller}) +\begin{verbatim} +\setacronymstyle{footnote-sm-desc} +\end{verbatim} +or (with \pkgopt{dua}) +\begin{verbatim} +\setacronymstyle{dua-desc} +\end{verbatim} \item[\pkgopt{smallcaps}] This option changes the definition of -\ics{newacronym} and the way that acronyms are displayed. This -option may have no effect if you define your own custom acronym -style. See \sectionref{sec:acronyms} for further details. +\ics{newacronym} and the way that acronyms are displayed. +This option may be replaced by: +\begin{verbatim} +\setacronymstyle{long-sc-short} +\end{verbatim} +or (with \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{long-sc-short-desc} +\end{verbatim} +or (with \pkgopt{description} and \pkgopt{footnote}) +\begin{verbatim} +\setacronymstyle{footnote-sc-desc} +\end{verbatim} \item[\pkgopt{smaller}] This option changes the definition of \ics{newacronym} and the way that acronyms are displayed. @@ -2267,25 +2370,57 @@ If you use this option, you will need to include the \sty{relsize} package or otherwise define \ics{textsmaller} or redefine \ics{acronymfont}. \end{important} -This option may have no effect if you define your own custom acronym -style. See \sectionref{sec:acronyms} for further details. +This option may be replaced by: +\begin{verbatim} +\setacronymstyle{long-sm-short} +\end{verbatim} +or (with \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{long-sm-short-desc} +\end{verbatim} +or (with \pkgopt{description} and \pkgopt{footnote}) +\begin{verbatim} +\setacronymstyle{footnote-sm-desc} +\end{verbatim} \item[\pkgopt{footnote}] This option changes the definition of -\ics{newacronym} and the way that acronyms are displayed. This -option has no effect if you define your own custom acronym style. See -\sectionref{sec:acronyms} for further details. +\ics{newacronym} and the way that acronyms are displayed. +This option may be replaced by: +\begin{verbatim} +\setacronymstyle{footnote} +\end{verbatim} +or (with \pkgopt{smallcaps}) +\begin{verbatim} +\setacronymstyle{footnote-sc} +\end{verbatim} +or (with \pkgopt{smaller}) +\begin{verbatim} +\setacronymstyle{footnote-sm} +\end{verbatim} +or (with \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{footnote-desc} +\end{verbatim} +or (with \pkgopt{smallcaps} and \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{footnote-sc-desc} +\end{verbatim} +or (with \pkgopt{smaller} and \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{footnote-sm-desc} +\end{verbatim} -\item[\pkgopt{dua}] This option changes the definition of -\ics{newacronym} so that acronyms are always expanded. This -option may have no effect if you define your own custom acronym style. -See \sectionref{sec:acronyms} for further details. -\item[\pkgopt{shortcuts}] This option provides shortcut commands -for acronyms. See \sectionref{sec:acronyms} for further details. -Alternatively you can use: -\begin{definition}[\DescribeMacro\DefineAcronymShortcuts] -\cs{DefineAcronymShortcuts} -\end{definition} +\item[\pkgopt{dua}] This option changes the definition of +\ics{newacronym} so that acronyms are always expanded. +This option may be replaced by: +\begin{verbatim} +\setacronymstyle{dua} +\end{verbatim} +or (with \pkgopt{description}) +\begin{verbatim} +\setacronymstyle{dua-desc} +\end{verbatim} \end{description} @@ -2329,6 +2464,46 @@ Remember to use the \pkgopt{nomain} package option if you're only interested in using this \texttt{numbers} glossary. \end{important} +\item[\pkgopt{index}] This option defines a new glossary type with +the label \texttt{index} via +\begin{verbatim} +\newglossary[ilg]{index}{ind}{idx}{\indexname}% +\end{verbatim} +It also defines +\begin{definition}[\DescribeMacro\printindex] +\cs{printindex}\oarg{options} +\end{definition} +which is a synonym for +\ics{printglossary}\texttt{[type=index,\meta{options}]} and +\begin{definition}[\DescribeMacro\newterm] +\cs{newterm}\oarg{options}\marg{term} +\end{definition} +which is a synonym for +\begin{alltt} +\ics{newglossaryentry}\marg{term}[type=index,name=\marg{term},% +description=\ics{nopostdesc},\meta{options}] +\end{alltt} + +\begin{important} +Remember to use the \pkgopt{nomain} package option if you're only +interested in using this \texttt{index} glossary. Note that you +can't mix this option with \ics{index}. Either use +\styfmt{glossaries} for the indexing or use a~custom indexing +package, such as \sty{makeidx}, \sty{index} or \sty{imakeidx}. +(You can, of course, load one of those packages and +load \styfmt{glossaries} without the \pkgopt{index} package option.) +\end{important} + +Since the index isn't designed for terms with descriptions, you +might also want to disable the hyperlinks for this glossary using +the package option \pkgopt[index]{nohypertypes} or the command +\begin{display} +\ics{GlsDeclareNoHyperList}\verb|{index}| +\end{display} + +The example file \samplefile{-index} illustrates the use of the +\pkgopt{index} package option. + \item[\pkgopt{compatible-2.07}] Compatibility mode for old documents created using version 2.07 or below. @@ -2337,16 +2512,17 @@ created using version 3.07 or below. \end{description} -\section{Setting Options After Package Loaded} +\section{Setting Options After the Package is Loaded} \label{sec:setupglossaries} Some of the options described above may also be set after the -\sty{glossaries} package has been loaded using +\styfmt{glossaries} package has been loaded using \begin{definition}[\DescribeMacro{\setupglossaries}] \cs{setupglossaries}\marg{key-val list} \end{definition} The following package options \textbf{can't} be used in -\cs{setupglossaries}: \pkgopt{xindy}, \pkgopt{xindygloss}, \pkgopt{makeindex}, +\cs{setupglossaries}: \pkgopt{xindy}, \pkgopt{xindygloss}, +\pkgopt{xindynoglsnumbers}, \pkgopt{makeindex}, \pkgopt{nolong}, \pkgopt{nosuper}, \pkgopt{nolist}, \pkgopt{notree}, \pkgopt{nostyles}, \pkgopt{nomain}, \pkgopt{compatible-2.07}, \pkgopt{translate}, \pkgopt{notranslate}, @@ -2357,7 +2533,7 @@ using commands like \ics{GlsSetXdyLanguage} (see \begin{important} I recommend you use this command as soon as possible after loading -\sty{glossaries} otherwise you might end up using it too late for +\styfmt{glossaries} otherwise you might end up using it too late for the change to take effect. For example, if you try changing the acronym styles (such as \pkgopt{smallcaps}) after you have started defining your acronyms, you are likely to get unexpected results. If @@ -2429,7 +2605,7 @@ For example: Note that this command must be used before \cs{makeglossaries}. If you use \gls{xindy}, you can have a different compositor for page -numbers starting with an uppercase alphabetical character using: +numbers starting with an upper case alphabetical character using: \begin{definition}[\DescribeMacro{\glsSetAlphaCompositor}] \cs{glsSetAlphaCompositor}\marg{symbol} \end{definition} @@ -2507,9 +2683,11 @@ any non-expandable commands or active characters. \begin{important} Note that although an accented character or other non-Latin -character, such as \'e or \th, looks like a plain character in your +character, such as \'e or \ss, looks like a plain character in your \texttt{.tex} file, it's actually a macro (an active character) and -can therefore can't be used in the label. +therefore can't be used in the label. Also be careful of +\sty{babel}'s options that change certain punctuation characters +(such as \texttt{:} or \texttt{-}) to active characters. \end{important} The second argument, \meta{key=value list}, is @@ -2551,25 +2729,25 @@ description, if required. If omitted, the value is set to the same as the \gloskey{description} key. \item[{\gloskey{text}}] How this entry will appear in the document text -when using \ics{gls} (or one of its uppercase variants). If this +when using \ics{gls} (or one of its upper case variants). If this field is omitted, the value of the \gloskey{name} key is used. \item[{\gloskey{first}}] How the entry will appear in the document text -on \firstuse\ with \ics{gls} (or one of its uppercase +on \firstuse\ with \ics{gls} (or one of its upper case variants). If this field is omitted, the value of the \gloskey{text} key is used. Note that if you use \ics{glspl}, \ics{Glspl}, \ics{GLSpl}, \ics{glsdisp} before using \ics{gls}, the \gloskey{firstplural} value won't be used with \ics{gls}. \item[{\gloskey{plural}}] How the entry will appear in the document text -when using \ics{glspl} (or one of its uppercase variants). If this +when using \ics{glspl} (or one of its upper case variants). If this field is omitted, the value is obtained by appending \ics{glspluralsuffix} to the value of the \gloskey{text} field. The default value of \ics{glspluralsuffix} is the letter \qt{s}. \item[{\gloskey{firstplural}}] How the entry will appear in the document text on \firstuse\ with \ics{glspl} (or one of its -uppercase variants). If this field is omitted, the value is obtained +upper case variants). If this field is omitted, the value is obtained from the \gloskey{plural} key, if the \gloskey{first} key is omitted, or by appending \ics{glspluralsuffix} to the value of the \gloskey{first} field, if the \gloskey{first} field is present. Note @@ -2594,13 +2772,12 @@ is set to the same as the \gloskey{symbol} key. \item[{\gloskey{sort}}] This value indicates how \gls{makeindex} or \gls{xindy} should sort this entry. If omitted, the value is given -by the \gloskey{name} field. In general, it's best to use the -\gloskey{sort} key if the \gloskey{name} contains commands (e.g.\ -\verb|\ensuremath{\alpha}|). Note that the package options -\pkgopt[def]{sort} and \pkgopt[use]{sort} override the -\gloskey{sort} key in \ics{newglossaryentry} and redefining -\ics{glsprestandardsort} can also be used to override the -\gloskey{sort} key (see \sectionref{sec:pkgopts-sort}). +by the \gloskey{name} field unless one of the package options +\pkgopt[def]{sort} and \pkgopt[use]{sort} have been used. In +general, it's best to use the \gloskey{sort} key if the +\gloskey{name} contains commands (e.g.\ \verb|\ensuremath{\alpha}|). +You can also override the \gloskey{sort} key by redefining +\ics{glsprestandardsort} (see \sectionref{sec:pkgopts-sort}). \item[{\gloskey{type}}] This specifies the label of the glossary in which this entry belongs. If omitted, the default glossary is @@ -2701,9 +2878,11 @@ multiple plurals (for a given term) then use the \gloskey{plural} key for one of them and one of the user keys to specify the other plural form. For example: \begin{verbatim} -\newglossaryentry{cow}{name=cow,description={a fully grown -female of any bovine animal (plural cows, archaic plural kine)}, -user1={kine}} +\newglossaryentry{cow}{% + name=cow,% + description={a fully grown female of any bovine animal + (plural cows, archaic plural kine)},% + user1={kine}} \end{verbatim} You can then use \verb|\glspl{cow}| to produce \qt{cows} and \verb|\glsuseri{cow}| to produce \qt{kine}. You can, of course, @@ -2735,7 +2914,7 @@ participles. For example: \newcommand*{\ingkey}{user1} \newcommand*{\edkey}{user2} -\newcommand*{\newterm}[3][]{% +\newcommand*{\newword}[3][]{% \newglossaryentry{#2}{% name={#2},% description={#3},% @@ -2746,8 +2925,8 @@ participles. For example: \end{verbatim} With the above definitions, I can now define terms like this: \begin{verbatim} -\newterm{play}{to take part in activities for enjoyment} -\newterm[\edkey={ran},\ingkey={running}]{run}{to move fast using +\newword{play}{to take part in activities for enjoyment} +\newword[\edkey={ran},\ingkey={running}]{run}{to move fast using the legs} \end{verbatim} and use them in the text: @@ -2782,7 +2961,8 @@ where: \item[\meta{default value}] is the default value to use if this key isn't used in an entry definition (this may reference the current entry label via \cs{glslabel}, but you will have to switch on -expansion via the starred version of \cs{glsaddkey}); +expansion via the starred version of \cs{glsaddkey} and protect +fragile commands); \item[\meta{no link cs}] is the control sequence to use analogous to commands like \ics{glsentrytext}; \item[\meta{no link ucfirst cs}] is the control sequence to use analogous @@ -3174,14 +3354,15 @@ commands occur at the start of the document, the entry details are being looked up before the entry has been defined. \end{enumerate} -To overcome these problems, \sty{glossaries} v4.0 modifies the -definition of \cs{newglossaryentry} at the beginning of the -\env{document} environment so that the definitions are written to an -external file (\cs{jobname}.\texttt{glsdefs}) which is then read in -at the start of the document on the next run. The entry will then -only be defined if it doesn't already exist. This means that the -entry can now be looked up in the glossary, even if the glossary -occurs at the beginning of the document. +To overcome these problems, as from version 4.0 the +\styfmt{glossaries} package modifies the definition of +\cs{newglossaryentry} at the beginning of the \env{document} +environment so that the definitions are written to an external file +(\cs{jobname}\filetype{.glsdefs}) which is then read in at the start +of the document on the next run. The entry will then only be defined +if it doesn't already exist. This means that the entry can now be +looked up in the glossary, even if the glossary occurs at the +beginning of the document. There are drawbacks to this mechanism: if you modify an entry definition, you need a second run to see the effect of your @@ -3209,7 +3390,7 @@ thesis or an article for a~journal or proceedings, you must plan what you write in advance. If you plan in advance, you should have a fairly good idea of the type of terminology that your document will contain, so while you are planning, create a new file with all your entry -definitions. If while you're writing your document, you remember +definitions. If, while you're writing your document, you remember another term you need, then you can switch over to your definition file and add it. Most text editors have the ability to have more than one file open at a time. @@ -3319,7 +3500,7 @@ If you use the \sty{hyperref} package, I strongly recommend you use \app{pdflatex} rather than \app{latex} to compile your document, if possible. The DVI format of \LaTeX\ has limitations with the hyperlinks that can cause a problem when used with the -\sty{glossaries} package. Firstly, the DVI format can't break a +\styfmt{glossaries} package. Firstly, the DVI format can't break a hyperlink across a line whereas PDF\LaTeX\ can. This means that long glossary entries (for example, the full form of an acronym) won't be able to break across a line with the DVI format. Secondly, the DVI @@ -3359,7 +3540,7 @@ Note that no check is performed to see if the glossary types listed in \pkgopt{nohypertypes} or \cs{GlsDeclareNoHyperList} have been defined. -\begin{important}\raggedright +\begin{important} The values must be fully expanded, so \textbf{don't} try \verb|nohypertypes=\acronymtype| or \verb|\GlsDeclareNoHyperList{\acronymtype}|. @@ -3387,15 +3568,20 @@ font, do: \begin{verbatim} \renewcommand*{\glstextformat}[1]{\textsf{#1}} \end{verbatim} +Further customisation can be done via \ics{defglsentryfmt} or by +redefining \ics{glsentryfmt}. See \sectionref{sec:glsdisplay} for +further details. Each entry has an associated conditional referred to as the -\firstuseflag. This determines whether \ics{gls}, -\ics{glspl} (and their uppercase variants) should use the -value of the \gloskey{first} or \gloskey{text} keys. Note that an +\firstuseflag. This determines whether \ics{gls} or +\ics{glspl} (or their upper case variants) should use the +value of the \gloskey{first}\slash\gloskey{firstplural} or +\gloskey{text}\slash\gloskey{plural} keys. Note that an entry can be used without affecting the \firstuseflag\ (for example, when used with \cs{glslink}). See \sectionref{sec:glsunset} for commands that unset or reset this conditional. + The command: \begin{definition}[\DescribeMacro{\glslink}] \cs{glslink}\oarg{options}\marg{label}\marg{text} @@ -3546,7 +3732,7 @@ the value of the \gloskey{first} key will be used. On completion, \cs{gls} will mark the entry's \gls{firstuseflag} as used. -There are two uppercase variants: +There are two upper case variants: \begin{definition}[\DescribeMacro{\Gls}] \cs{Gls}\oarg{options}\marg{label}\oarg{insert} \end{definition} @@ -3555,7 +3741,7 @@ and \cs{GLS}\oarg{options}\marg{label}\oarg{insert} \end{definition} which make the first letter of the link text or all the link text -uppercase, respectively. +upper case, respectively. The final optional argument \meta{insert}, allows you to insert some additional text into the link text. By default, this will @@ -3607,29 +3793,29 @@ $\gls{Falpha}[^2]$ \end{verbatim} \end{important} -Note that \ics{glslink} doesn't use or affect the \firstuseflag, -nor does it use \ics{glsdisplay} or \ics{glsdisplayfirst} (see -\sectionref{sec:glsdisplay}). Instead, you can use: -\begin{definition}[\DescribeMacro{\glsdisp}] +Note that \ics{glslink} doesn't use or affect the \firstuseflag, nor +does it use \ics{glsentryfmt} or the equivalent definition provided +by \ics{defglsentryfmt} (see \sectionref{sec:glsdisplay}). Instead, +you can use: \begin{definition}[\DescribeMacro{\glsdisp}] \cs{glsdisp}\oarg{options}\marg{label}\marg{link text} -\end{definition} -This behaves in the same way as \ics{gls}, except that it uses -\meta{link text} instead of the value of the \gloskey{first} -or \gloskey{text} key. (Note that this command always sets -\meta{insert} to nothing.) This command affects the \firstuseflag, -and uses \ics{glsdisplay} or \ics{glsdisplayfirst}. +\end{definition} This behaves in the same way as \ics{gls}, except +that it uses \meta{link text} instead of the value of the +\gloskey{first} or \gloskey{text} key. (Note that this command +always sets \meta{insert} to nothing.) This command affects the +\firstuseflag, and uses \ics{glsentryfmt} or the equivalent +definition provided by \ics{defglsentryfmt}. The command: \begin{definition}[\DescribeMacro{\glstext}] \cs{glstext}\oarg{options}\marg{label}\oarg{insert} \end{definition} is similar to \ics{gls} except that it always uses the value -of the \gloskey{text} key and does not affect the -\firstuseflag. -Unlike \cs{gls}, the inserted text \meta{insert} -is always appended to the link text since \cs{glstext} doesn't -use \ics{glsdisplay} or \ics{glsdisplayfirst}. (The same is -true for all the following commands described in this section.) +of the \gloskey{text} key and does not affect the \firstuseflag. +Unlike \cs{gls}, the inserted text \meta{insert} is always appended +to the link text since \cs{glstext} doesn't use \ics{glsentryfmt} or +the equivalent definition provided by \ics{defglsentryfmt}. (The +same is true for all the following commands described in the rest of this +section.) There are also analogous commands: \begin{definition}[\DescribeMacro{\Glstext}] @@ -3641,12 +3827,6 @@ There are also analogous commands: As before, these commands also have a starred version that disable the hyperlink. -\begin{important} -When used with acronyms, these commands don't use \ics{acronymfont}. -For example, if you use the \pkgopt{smallcaps} package option, -\cs{gls} will use small caps but \cs{glstext} won't. -\end{important} - The command: \begin{definition}[\DescribeMacro{\glsfirst}] \cs{glsfirst}\oarg{options}\marg{label}\oarg{insert} @@ -3685,12 +3865,6 @@ There are also analogous commands: As before, these commands also have a starred version that disable the hyperlink. -\begin{important} -When used with acronyms, these commands don't use \ics{acronymfont}. -For example, if you use the \pkgopt{smallcaps} package option, -\cs{glspl} will use small caps but \cs{glsplural} won't. -\end{important} - The command: \begin{definition}[\DescribeMacro{\glsfirstplural}] \cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert} @@ -3835,7 +4009,7 @@ the hyperlink. Similarly for the other user keys: \label{sec:glsdisplay} The format of the \gls{linktext} for \ics{gls}, \ics{glspl} -and their uppercase variants and also for \ics{glsdisp} is governed +and their upper case variants and also for \ics{glsdisp} is governed by\footnote{\ics{glsdisplayfirst} and \ics{glsdisplay} are now deprecated. Backwards compatibility should be preserved but you may need to use the \pkgopt{compatible-3.07} option}: @@ -3854,7 +4028,7 @@ This is the label of the entry being referenced. \cs{glscustomtext} \end{definition} This is the custom text supplied in \cs{glsdisp}. It's always empty -for \ics{gls}, \ics{glspl} and their uppercase variants. (You can +for \ics{gls}, \ics{glspl} and their upper case variants. (You can use \sty{etoolbox}'s \cs{ifdefempty} to determine if \cs{glscustomtext} is empty.) @@ -3862,7 +4036,7 @@ use \sty{etoolbox}'s \cs{ifdefempty} to determine if \cs{glsinsert} \end{definition} The custom text supplied in the final optional argument to \cs{gls}, -\cs{glspl} and their uppercase variants. +\cs{glspl} and their upper case variants. \begin{definition}[\DescribeMacro{\glsifplural}] \cs{glsifplural}\marg{true text}\marg{false text} @@ -3889,6 +4063,49 @@ This uses the above commands to display just the \gloskey{first}, \gloskey{text}, \gloskey{plural} or \gloskey{firstplural} keys (or the custom text) with the insert text appended. +Alternatively, if want to change the entry format for acronyms +(defined via \ics{newacronym}) you can use: +\begin{definition}[\DescribeMacro{\glsgenacfmt}] +\cs{glsgenacfmt} +\end{definition} +This uses the values from the \gloskey{long}, \gloskey{short}, +\gloskey{longplural} and \gloskey{shortplural} keys, rather than +using the \gloskey{text}, \gloskey{plural}, \gloskey{first} +and \gloskey{firstplural} keys. The first use singular text is obtained via: +\begin{definition}[\DescribeMacro{\genacrfullformat}] +\cs{genacrfullformat}\marg{label}\marg{insert} +\end{definition} +instead of from the \gloskey{first} key, and the first use plural +text is obtained via: +\begin{definition}[\DescribeMacro{\genplacrfullformat}] +\cs{genplacrfullformat}\marg{label}\marg{insert} +\end{definition} +instead of from the \gloskey{firstplural} key. +In both cases, \meta{label} is the entry's label and \meta{insert} +is the insert text provided in the final optional argument of +commands like \ics{gls}. The default behaviour is to do the long +form (or plural long form) followed by \meta{insert} and a~space and the short form (or plural +short form) in parentheses, where the short form is in the argument +of \ics{firstacronymfont}. There are also first letter upper case +versions: +\begin{definition}[\DescribeMacro{\Genacrfullformat}] +\cs{Genacrfullformat}\marg{label}\marg{insert} +\end{definition} +and +\begin{definition}[\DescribeMacro{\Genplacrfullformat}] +\cs{Genplacrfullformat}\marg{label}\marg{insert} +\end{definition} +By default these perform a protected expansion on their no-case-change +equivalents and then use \ics{makefirstuc} to convert the first +character to upper case. If there are issues caused by this +expansion, you will need to redefine those commands to explicitly +use commands like \ics{Glsentrylong} (which is what the predefined +acronym styles, such as \acrstyle{long-short}, do). Otherwise, you +only need to redefine \ics{genacrfullformat} and +\ics{genplacrfullformat} to change the behaviour of +\ics{glsgenacfmt}. See \sectionref{sec:acronyms} for further details +on changing the style of acronyms. + \begin{important} Note that \cs{glsentryfmt} is not used by \ics{glslink} or any of the other commands, such as \ics{glstext}. @@ -3931,7 +4148,7 @@ For a complete document, see the sample file \samplefile{-entryfmt}. If you have multiple glossaries, changing \cs{glsentryfmt} will change the way entries for all of the glossaries appear when using the commands -\ics{gls}, \ics{glspl}, their uppercase variants and \ics{glsdisp}. +\ics{gls}, \ics{glspl}, their upper case variants and \ics{glsdisp}. If you only want the change to affect entries for a given glossary, then you need to use @@ -3949,7 +4166,8 @@ Suppose you have created a new glossary called displayed on \firstuse\ so that it includes the symbol, you can do: \begin{verbatim} \defglsentryfmt[notation]{\glsgenentryfmt - \ifglsused{\glslabel}{}{\space(denoted \glsentrysymbol{\glslabel})}} + \ifglsused{\glslabel}{}{\space + (denoted \glsentrysymbol{\glslabel})}} \end{verbatim} Now suppose you have defined an entry as follows: \begin{verbatim} @@ -3961,6 +4179,22 @@ Now suppose you have defined an entry as follows: \end{verbatim} The \glslink{firstuse}{first time} you reference this entry it will be displayed as: \qt{set (denoted $S$)} (assuming \ics{gls} was used). + +Alternatively, if you expect all the symbols to be set in math mode, +you can do: +\begin{verbatim} +\defglsentryfmt[notation]{\glsgenentryfmt + \ifglsused{\glslabel}{}{\space + (denoted $\glsentrysymbol{\glslabel}$)}} +\end{verbatim} +and define entries like this: +\begin{verbatim} +\newglossaryentry{set}{type=notation, + name=set, + description={A collection of objects}, + symbol={S} +} +\end{verbatim} \end{example} Remember that if you use the \gloskey{symbol} key, you need to use a @@ -4133,7 +4367,7 @@ ignore this location in the number list. The optional argument it defaults to the list of all defined glossaries. \begin{example}{Dual Entries}{ex:dual} -The sample file \samplefile{-dual} makes use of \cs{glsadd} to +The example file \samplefile{-dual} makes use of \cs{glsadd} to allow for an entry that should appear both in the main glossary and in the list of acronyms. This example sets up the list of acronyms using the \pkgopt{acronym} package option: @@ -4153,9 +4387,9 @@ entries: } \end{verbatim} This has the following syntax: -\begin{definition} +\begin{alltt} \ics{newdualentry}\oarg{options}\marg{label}\marg{abbrv}\marg{long}\marg{description} -\end{definition} +\end{alltt} You can then define a new dual entry: \begin{verbatim} \newdualentry{svm}% label @@ -4336,7 +4570,8 @@ Commands that aren't expandable will be ignored by PDF bookmarks, so you will need to provide an alternative via \sty{hyperref}'s \cs{texorpdfstring} if you want to use them in sectioning commands. (This isn't specific to the \styfmt{glossaries} package.) See the -\sty{hyperref} documentation for further details. +\sty{hyperref} documentation for further details. All the commands +that convert the first letter to upper case aren't expandable. \end{important} \begin{definition}[\DescribeMacro{\glsentryname}] @@ -4347,7 +4582,7 @@ you will need to provide an alternative via \sty{hyperref}'s \end{definition} These commands display the name of the glossary entry given by \meta{label}, as specified by the \gloskey{name} key. -\cs{Glsentryname} makes the first letter uppercase. +\cs{Glsentryname} makes the first letter upper case. Neither of these commands check for the existence of \meta{label}. The first form \cs{glsentryname} is expandable (unless the name contains unexpandable commands). @@ -4368,7 +4603,7 @@ example: \cs{Glossentryname}\marg{label} \end{definition} This is like \cs{glossentryname} but makes the first letter of the -name uppercase. +name upper case. \begin{definition}[\DescribeMacro{\glsentrytext}] \cs{glsentrytext}\marg{label} @@ -4378,7 +4613,7 @@ name uppercase. \end{definition} These commands display the subsequent use text for the glossary entry given by \meta{label}, as specified by the \gloskey{text} key. -\cs{Glsentrytext} makes the first letter uppercase. +\cs{Glsentrytext} makes the first letter upper case. The first form is expandable (unless the text contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -4392,7 +4627,7 @@ existence of \meta{label}. These commands display the subsequent use plural text for the glossary entry given by \meta{label}, as specified by the \gloskey{plural} key. \cs{Glsentryplural} makes the first letter -uppercase. +upper case. The first form is expandable (unless the value of that key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -4405,7 +4640,7 @@ existence of \meta{label}. \end{definition} These commands display the \firstusetext\ for the glossary entry given by \meta{label}, as specified by the \gloskey{first} key. -\cs{Glsentryfirst} makes the first letter uppercase. +\cs{Glsentryfirst} makes the first letter upper case. The first form is expandable (unless the value of that key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -4419,7 +4654,7 @@ existence of \meta{label}. These commands display the plural form of the \firstusetext\ for the glossary entry given by \meta{label}, as specified by the \gloskey{firstplural} key. \cs{Glsentryfirstplural} makes the first -letter uppercase. +letter upper case. The first form is expandable (unless the value of that key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -4431,7 +4666,7 @@ existence of \meta{label}. \cs{Glsentrydesc}\marg{label} \end{definition} These commands display the description for the glossary entry given -by \meta{label}. \cs{Glsentrydesc} makes the first letter uppercase. +by \meta{label}. \cs{Glsentrydesc} makes the first letter upper case. The first form is expandable (unless the value of that key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -4447,7 +4682,7 @@ display the description. \cs{Glossentrydesc}\marg{label} \end{definition} This is like \cs{glossentrydesc} but converts the first letter to -uppercase. This command is not expandable. +upper case. This command is not expandable. \begin{definition}[\DescribeMacro{\glsentrydescplural}] \cs{glsentrydescplural}\marg{label} @@ -4457,7 +4692,7 @@ uppercase. This command is not expandable. \end{definition} These commands display the plural description for the glossary entry given by \meta{label}. \cs{Glsentrydescplural} makes the first -letter uppercase. +letter upper case. The first form is expandable (unless the value of that key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -4470,7 +4705,7 @@ existence of \meta{label}. \cs{Glsentrysymbol}\marg{label} \end{definition} These commands display the symbol for the glossary entry given by -\meta{label}. \cs{Glsentrysymbol} makes the first letter uppercase. +\meta{label}. \cs{Glsentrysymbol} makes the first letter upper case. The first form is expandable (unless the value of that key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -4486,7 +4721,7 @@ display the symbol. \cs{Glossentrysymbol}\marg{label} \end{definition} This is like \cs{glossentrysymbol} but converts the first letter to -uppercase. This command is not expandable. +upper case. This command is not expandable. \begin{definition}[\DescribeMacro{\glsentrysymbolplural}] \cs{glsentrysymbolplural}\marg{label} @@ -4496,7 +4731,7 @@ uppercase. This command is not expandable. \end{definition} These commands display the plural symbol for the glossary entry given by \meta{label}. \cs{Glsentrysymbolplural} makes the first -letter uppercase. +letter upper case. The first form is expandable (unless the value of that key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -4541,8 +4776,8 @@ These commands display the value of the user keys for the glossary entry given by \meta{label}. The lower case forms are expandable (unless the value of the key contains unexpandable commands). The commands beginning with an -uppercase letter convert the first letter of the required value to -uppercase and are not expandable. None of these commands check for +upper case letter convert the first letter of the required value to +upper case and are not expandable. None of these commands check for the existence of \meta{label}. \begin{definition}[\DescribeMacro{\glshyperlink}] @@ -5056,7 +5291,7 @@ separated by white space. For example: } \end{verbatim} -\begin{important}\raggedright +\begin{important} Note that \cs{GlsSetXdyLocationClassOrder} has no effect if \ics{noist} is used or if \ics{makeglossaries} is omitted. \cs{GlsSetXdyLocationClassOrder} must be used before @@ -5080,7 +5315,7 @@ The argument may also be the keyword \texttt{none}, to indicate that there should be no range formations. See the \gls{xindy} manual for further details on range formations. -\begin{important}\raggedright +\begin{important} Note that \cs{GlsSetXdyMinRangeLength} has no effect if \ics{noist} is used or if \ics{makeglossaries} is omitted. \cs{GlsSetXdyMinRangeLength} must be used before @@ -5112,7 +5347,7 @@ Roman alphabet, you can change this using: \cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter} \end{definition} -\begin{important}\raggedright +\begin{important} Note that \cs{GlsSetXdyFirstLetterAfterDigits} has no effect if \ics{noist} is used or if \ics{makeglossaries} is omitted. \cs{GlsSetXdyFirstLetterAfterDigits} must be used before @@ -5191,99 +5426,30 @@ useful means to define acronyms. For convenience, the \end{definition} This uses \ics{newglossaryentry} to create an entry with the given -label in the glossary given by \ics{acronymtype}. Amongst other -things, it sets up the \gloskey{first} and \gloskey{text} keys and, -depending on the acronym style, may also use \ics{defglsentryfmt} -(see \sectionref{sec:glsdisplay}). +label in the glossary given by \ics{acronymtype}. It also uses the +\gloskey{long}, \gloskey{longplural}, \gloskey{short} and +\gloskey{shortplural} keys to store the long and abbreviated forms +and their plurals. The optional argument \marg{key-val list} allows you to specify keys -such as \gloskey{description} (when used with the -\pkgopt{description} package option, described below) or you can +such as \gloskey{description} (when used with one of the styles that +require a description, described in +\sectionref{sec:setacronymstyle}) or you can override plural forms of \meta{abbrv} or \meta{long} using the \gloskey{shortplural} or \gloskey{longplural} keys. For example: \begin{verbatim} -\newacronym[longplural={diagonal matrices}]{dm}{DM}{diagonal -matrix} +\newacronym[longplural={diagonal matrices}]% + {dm}{DM}{diagonal matrix} \end{verbatim} If the \firstuse\ uses the plural form, \verb|\glspl{dm}| will display: diagonal matrices (DMs). - -The following package options are available to change the acronym -style: - -\begin{description} -\item[\pkgopt{description}] -With this package option, the \gloskey{description} key needs to be -set in the optional argument \meta{key-val list} of \cs{newacronym}. -(If this package option isn't used, the long form \meta{long} is put -in the \gloskey{description} key.) - -\item[\pkgopt{footnote}] -With this package option, on \gls{firstuse} the long form \meta{long} is -placed in a footnote. By default the long form in the footnote will -link to the relevant entry in the glossary or list of acronyms. You -can prevent this link by doing: -\begin{verbatim} -\let\acrfootnote\acrnolinkfootnote -\end{verbatim} - -\item[\pkgopt{smallcaps}] -With this package option, the short form \meta{abbrv} is typeset -using \ics{textsc}. (Recall that \cs{textsc} converts lower case -characters into small capitals and leaves upper case characters as -they are. Therefore, you need to have lower case characters in -\meta{abbrv} for this option to have an effect.) - -\hypertarget{boldsc}{}% -\begin{important}% -Some fonts don't support bold smallcaps, so you may need to redefine -\ics{glsnamefont} (see \sectionref{sec:printglossary}) to switch to -medium weight if you are using a glossary style that displays entry -names in bold. -\end{important} - -\item[\pkgopt{smaller}] -This is similar to \pkgopt{smallcaps}, except that \ics{textsmaller} -is used instead of \ics{textsc}. Note that the \styfmt{glossaries} -package doesn't define \ics{textsmaller} nor does it load any -package that does so. - -\begin{important} -If you use this option, you must make sure -\ics{textsmaller} is defined (for example by loading \sty{relsize}). -\end{important} - -\item[\pkgopt{dua}] -This option will set both the \gloskey{first} and \gloskey{text} -keys to the long form \meta{long}. -\end{description} - -If you want to define your own custom acronym style, see -\sectionref{sec:customacronym}. +Since \ics{newacronym} uses \ics{newglossaryentry}, you can use +commands like \ics{gls} and \ics{glsreset} as with any other +glossary entry. \begin{important} -If you try using \ics{newglossaryentry} for entries in a designated -list of acronyms in combination with any of the above named package -options you may get unexpected results such as empty -brackets or empty footnotes. - -If you don't intend to use \ics{newacronym} you should skip this section -and not use the above package options. -\end{important} - -As mentioned in \sectionref{sec:pkgopts-sec}, the command -\ics{acronymtype} is the name of the glossary in which the acronyms -should appear by default. If the \pkgopt{acronym} package option has been used, -this will be \texttt{acronym}, otherwise it will be \texttt{main}. -The acronyms can then be used in exactly the same way as any other -glossary entry. If you want more than one list of acronyms, you must -identify the others using the package options \pkgopt{acronymlists}. -This ensures that options such as \pkgopt{footnote} and -\pkgopt{smallcaps} work for the additional lists of acronyms. - -\begin{important}\raggedright Since \cs{newacronym} sets \verb|type=\acronymtype|, if you want to load a file containing acronym definitions using \ics{loadglsentries}\oarg{type}\marg{filename}, the optional argument @@ -5292,58 +5458,24 @@ type as \verb|type=\glsdefaulttype| in the optional argument to \ics{newacronym}. See \sectionref{sec:loadglsentries}. \end{important} -Since \ics{newacronym} uses \ics{newglossaryentry}, you can use -commands like \ics{gls} and \ics{glsreset} as with any other -glossary entry. - \begin{example}{Defining an Acronym}{ex:newacronym} The following defines the acronym IDN: \begin{verbatim} \newacronym{idn}{IDN}{identification number} \end{verbatim} \verb|\gls{idn}| will produce \qt{identification number (IDN)} on -\firstuse\ and \qt{IDN} on subsequent uses. If you want to use the -\pkgopt{smallcaps} package option, you need to use lower case +\firstuse\ and \qt{IDN} on subsequent uses. If you want to use one +of the smallcaps acronym styles, described in +\sectionref{sec:setacronymstyle}, you need to use lower case characters for the shortened form: \begin{verbatim} \newacronym{idn}{idn}{identification number} \end{verbatim} Now \verb|\gls{idn}| will produce \qt{identification number -(\textsc{idn})} on \firstuse\ and \qt{\textsc{IDN}} on subsequent +(\textsc{idn})} on \firstuse\ and \qt{\textsc{idn}} on subsequent uses. \end{example} -If you use any of the package options \pkgopt{smallcaps}, -\pkgopt{smaller}, \pkgopt{description} or \pkgopt{footnote}, the -short form \meta{abbrv} will be displayed in the document using: -\begin{definition}[\DescribeMacro{\acronymfont}] -\cs{acronymfont}\marg{text} -\end{definition} -and -\begin{definition}[\DescribeMacro{\firstacronymfont}] -\cs{firstacronymfont}\marg{text} -\end{definition} -where \cs{firstacronymfont} is applied on \firstuse\ and -\cs{acronymfont} is applied on subsequent use. Note that if you -don't use any of the above package options, changing the definition -of \cs{acronymfont} or \cs{firstacronymfont} will have no effect. In -this case, the recommended route is to use either the -\pkgopt{smaller} or the \pkgopt{smallcaps} package option and -redefine \cs{acronymfont} and \cs{firstacronymfont} as required. -(The \pkgopt{smallcaps} option sets the default plural suffix in an -upright font to cancel the effect of \ics{textsc}, whereas -\pkgopt{smaller} sets the suffix in the surrounding font.) For -example, if you want acronyms in a normal font on \gls{firstuse} and -emphasized on subsequent use, do: -\begin{verbatim} -\usepackage[smaller]{glossaries} -\renewcommand*{\firstacronymfont}[1]{#1} -\renewcommand*{\acronymfont}[1]{\emph{#1}} -\end{verbatim} -(Note that it is for this reason that the \sty{relsize} package is -not automatically loaded when selecting the \pkgopt{smaller} package -option as it may not actually be required.) - There are commands analogous to \ics{glstext} (described in \sectionref{sec:glslink}) that allow you to access just the short form, just the long form or the full form, without affecting the @@ -5403,18 +5535,11 @@ And for the full form: \begin{definition}[\DescribeMacro{\acrfull}] \cs{acrfull}\oarg{options}\marg{label}\oarg{insert} \end{definition} -This defaults to \meta{long} (\ics{acronymfont}\marg{short}) -regardless of the package options. This format can be changed by -redefining: -\begin{definition}[\DescribeMacro\acrfullformat] -\cs{acrfullformat}\marg{long}\marg{short} +This defaults to \meta{long} (\ics{acronymfont}\marg{short}). +The format (including hyperlinks) can be modified by redefining: +\begin{definition}[\DescribeMacro{\acrfullfmt}] +\cs{acrfullfmt}\marg{options}\marg{label}\marg{insert} \end{definition} -For example, to change \cs{acrfull} to produce -\cs{acronymfont}\marg{short} (\meta{long}) -you can redefine \cs{acrfullformat} as: -\begin{verbatim} -\renewcommand{\acrfullformat}[2]{#2\space(#1)} -\end{verbatim} There are also analogous upper case variants: \begin{definition}[\DescribeMacro{\Acrfull}] @@ -5423,6 +5548,14 @@ There are also analogous upper case variants: \begin{definition}[\DescribeMacro{\ACRfull}] \cs{ACRfull}\oarg{options}\marg{label}\oarg{insert} \end{definition} +The formats (including hyperlinks) can be modified by redefining: +\begin{definition}[\DescribeMacro{\Acrfullfmt}] +\cs{Acrfullfmt}\marg{options}\marg{label}\marg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\ACRfullfmt}] +\cs{ACRfullfmt}\marg{options}\marg{label}\marg{insert} +\end{definition} + As before there are also plural versions: \begin{definition}[\DescribeMacro\acrfullpl] \cs{acrfullpl}\oarg{options}\marg{label}\oarg{insert} @@ -5433,6 +5566,16 @@ As before there are also plural versions: \begin{definition}[\DescribeMacro\ACRfullpl] \cs{ACRfullpl}\oarg{options}\marg{label}\oarg{insert} \end{definition} +The formats (including hyperlinks) can be modified by redefining: +\begin{definition}[\DescribeMacro{\acrfullplfmt}] +\cs{acrfullplfmt}\marg{options}\marg{label}\marg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\Acrfullplfmt}] +\cs{Acrfullplfmt}\marg{options}\marg{label}\marg{insert} +\end{definition} +\begin{definition}[\DescribeMacro{\ACRfullplfmt}] +\cs{ACRfullplfmt}\marg{options}\marg{label}\marg{insert} +\end{definition} If you find the above commands too cumbersome to write, you can use the \pkgopt{shortcuts} package option to activate the shorter @@ -5514,269 +5657,344 @@ using: \begin{definition}[\DescribeMacro{\Glsentryfullpl}] \cs{Glsentryfullpl}\marg{label} \end{definition} -(These also use \ics{acrfullformat}.) +(These may be redefined by the acronym style.) -\section{Predefined Acronym Styles} -\label{sec:predefinedacrstyles} +\section{Changing the Acronym Style} +\label{sec:setacronymstyle} -Some of the acronym-related package options may be combined. Listed -below are the effects of different combinations. If you use an -invalid combination, you'll get an error message. -If none of these styles suit your requirements, see -\sectionref{sec:customacronym} to create your own custom style. +It may be that the default style doesn't suit your requirements in +which case you can switch to another styles via +\begin{definition}[\DescribeMacro{\setacronymstyle}] +\cs{setacronymstyle}\marg{style name} +\end{definition} +where \meta{style name} is the name of the required style. -\begin{description} -\item[\pkgopt{description},\pkgopt{footnote}]\ifpdf\mbox{}\par\fi -When these two package options are used together, the \firstuse\ displays -the entry as: -\begin{display} -\cs{firstacronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long} -\end{display} -while subsequent use displays the entry as: -\begin{display} -\cs{acronymfont}\marg{abbrv}\meta{insert} -\end{display} -where \meta{insert} indicates the text supplied in the final -optional argument to \ics{gls}, \ics{glspl} or their uppercase -variants. - -\item[\pkgopt{dua}]\ifpdf\mbox{}\par\fi -The \pkgopt{dua} package option always makes \ics{gls} display the -expanded form and so may not be used with \pkgopt{footnote}, -\pkgopt{smaller} or \pkgopt{smallcaps}. Both \firstuse\ and subsequent -use displays the entry in the form: -\begin{display} -\meta{long}\meta{insert} -\end{display} -You can, however, access the short form using \ics{acrshort} and its -variants. +\begin{important} +You must use \cs{setacronymstyle} \emph{before} you define the +acronyms with \cs{newacronym}. If you have multiple glossaries +representing lists of acronyms, you must use \cs{setacronymstyle} +\emph{after} using \cs{DeclareAcronymList}. +\end{important} -\item[\pkgopt{description}]\ifpdf\mbox{}\par\fi -This package option displays the entry on \firstuse\ as: -\begin{display} -\meta{long}\meta{insert} (\ics{firstacronymfont}\marg{abbrv}) -\end{display} -while subsequent use displays the entry as: -\begin{display} -\cs{acronymfont}\marg{abbrv}\meta{insert} -\end{display} +Note that unlike the default behaviour of \cs{newacronym}, the +styles used via \cs{setacronymstyle} don't use the \gloskey{first} +or \gloskey{text} keys, but instead they use \ics{defglsentryfmt} to +set a~custom format that uses the \gloskey{long} and \gloskey{short} +keys (or their plural equivalents). This means that these styles +cope better with plurals that aren't formed by simply appending the +singular form with the letter ``s''. In fact, most of the predefined +styles use \ics{glsgenacfmt} and modify the definitions of commands +like \ics{genacrfullformat}. + +Note that when you use \cs{setacronymstyle} the \gloskey{name} key +is set to +\begin{definition}[\DescribeMacro{\acronymentry}] +\cs{acronymentry}\marg{label} +\end{definition} +and the \gloskey{sort} key is set to +\begin{definition}[\DescribeMacro{\acronymsort}] +\cs{acronymsort}\marg{short}\marg{long} +\end{definition} +These commands are redefined by the acronym styles. However, you can +redefine them again after the style has been set but before you use +\cs{newacronym}. Protected expansion is performed on \cs{acronymsort} +when the entry is defined. + +\subsection{Predefined Acronym Styles} +\label{sec:predefinedacrstyles} -Note that with this option, you need to specify the description -using the \gloskey{description} key in the optional argument -of \ics{newacronym}. +The \styfmt{glossaries} package provides a~number of predefined +styles. These styles apply +\begin{definition}[\DescribeMacro{\firstacronymfont}] +\cs{firstacronymfont}\marg{text} +\end{definition} +to the short form on first use and +\begin{definition}[\DescribeMacro{\acronymfont}] +\cs{acronymfont}\marg{text} +\end{definition} +on subsequent use. The styles modify the definition of +\cs{acronymfont} as required, but \ics{firstacronymfont} is only set +once by the package when it's loaded. By default +\ics{firstacronymfont}\marg{text} is the same as +\ics{acronymfont}\marg{text}. +If you want the short form displayed differently on first use, you +can redefine \ics{firstacronymfont} independently of the acronym +style. -\item[\pkgopt{footnote}]\ifpdf\mbox{}\par\fi -This package option displays the entry on \firstuse\ as: -\begin{display} -\cs{firstacronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long} -\end{display} -while subsequent use displays the entry as: -\begin{display} -\cs{acronymfont}\marg{abbrv}\meta{insert} -\end{display} -Acronyms will be sorted according to the short form. +The predefined styles that contain \texttt{sc} in their name +(for example \acrstyle{long-sc-short}) redefine \cs{acronymfont} to +use \ics{textsc} (so the short form needs to be specified in lower +case). -Note that on \firstuse, it is the long form in the footnote that -links to the relevant glossary entry (where hyperlinks are enabled), -whereas on subsequent use, the acronym links to the relevant -glossary entry. You can suppress the long form link by setting: -\begin{verbatim} -\let\acrfootnote\acrnolinkfootnote -\end{verbatim} +\hypertarget{boldsc}{}% +\begin{important}% +Some fonts don't support bold smallcaps, so you may need to redefine +\ics{glsnamefont} (see \sectionref{sec:printglossary}) to switch to +medium weight if you are using a glossary style that displays entry +names in bold and you have chosen an acronym style that uses +\ics{textsc}. +\end{important} -\item[\pkgopt{smallcaps}]\ifpdf\mbox{}\par\fi -If neither the \pkgopt{footnote} nor \pkgopt{description} options -have been set, this option displays the entry on \firstuse\ as: -\begin{display} -\meta{long}\meta{insert} (\ics{firstacronymfont}\marg{abbrv}) -\end{display} -while subsequent use displays the entry as: -\begin{display} -\cs{acronymfont}\marg{abbrv}\meta{insert} -\end{display} -where \ics{acronymfont} is set to \verb|\textsc{#1}|. +The predefined styles that contain \texttt{sm} in their name +(for example \acrstyle{long-sm-short}) redefine \cs{acronymfont} to +use \ics{textsmaller}. +\hypertarget{smaller}{}% \begin{important} -Note that since the acronym is displayed using \ics{textsc}, -the short form, \meta{abbrv}, should be specified in lower case. -\ifpdf(Recall that "\textsc{abc}" produces \textsc{abc} whereas -"\textsc{ABC}" produces \textsc{ABC}.)\fi +Note that the \styfmt{glossaries} package doesn't define or load any package that +defines \ics{textsmaller}. If you use one of the acronym styles that +set \ics{acronymfont} to \cs{textsmaller} you must +explicitly load the \sty{relsize} package or otherwise define +\cs{textsmaller}. +\end{important} -See also the \hyperlink{boldsc}{earlier note} regarding combining -bold and smallcaps. +The remaining predefined styles redefine \cs{acronymfont}\marg{text} +to simply do its argument \meta{text}. + +\begin{important} +In most cases, the predefined styles adjust \ics{acrfull} and +\ics{glsentryfull} (and their plural and upper case variants) to +reflect the style. The only exceptions to this are the +\acrstyle{dua} and \acrstyle{footnote} styles (and their variants). \end{important} -\item[\pkgopt{smaller}]\ifpdf\mbox{}\par\fi -If neither the \pkgopt{footnote} nor \pkgopt{description} options -have been set, this option displays the entry on \firstuse\ as: -\begin{display} -\meta{long}\meta{insert} (\ics{firstacronymfont}\marg{abbrv}) -\end{display} -while subsequent use displays the entry as: -\begin{display} -\ics{acronymfont}\marg{abbrv}\meta{insert} -\end{display} -where \ics{acronymfont} is set to -\verb|\textsmaller{#1}|.\footnote{Note that this was changed from -using \ics{smaller} to \ics{textsmaller} as declarations -cause a problem for \ics{makefirstuc}.} -The entries will be sorted according to the short form. +The following styles are supplied by the \styfmt{glossaries} +package: +\begin{itemize} +\item \acrstyle{long-short}, \acrstyle{long-sc-short}, +\acrstyle{long-sm-short}: + +With these three styles, acronyms are displayed in the form +\begin{definition} +\meta{long} (\ics{firstacronymfont}\marg{short}) +\end{definition} +on first use and +\begin{definition} +\ics{acronymfont}\marg{short} +\end{definition} +on subsequent use. +They also set \cs{acronymsort}\marg{short}\marg{long} to just +\meta{short}. This means that the acronyms are sorted according to +their short form. In addition, \cs{acronymentry}\marg{label} is set +to just the short form (enclosed in \cs{acronymfont}) and the +\gloskey{description} key is set to the long form. + +\item \acrstyle{short-long}, \acrstyle{sc-short-long}, +\acrstyle{sm-short-long}: + +These three styles are analogous to the above three styles, except +the display order is swapped to +\begin{definition} +\ics{firstacronymfont}\marg{short} (\meta{long}) +\end{definition} +on first use. + +Note, however, that \ics{acronymsort} and \ics{acronymentry} are the +same as for the \meta{long} (\meta{short}) styles above, so the +acronyms are still sorted according to the short form. + +\item \acrstyle{long-short-desc}, \acrstyle{long-sc-short-desc}, +\acrstyle{long-sm-short-desc}: + +These are like the \acrstyle{long-short}, \acrstyle{long-sc-short} +and \acrstyle{long-sm-short} styles described above, except that the +\gloskey{description} key must be supplied in the optional argument +of \ics{newacronym}. They also redefine \ics{acronymentry} to +\marg{long} (\cs{acronymfont}\marg{short}) and redefine +\ics{acronymsort}\marg{short}\marg{long} to just \meta{long}. +This means that the acronyms are sorted according to the long form, +and in the list of acronyms the name field has the long form +followed by the short form in parentheses. I~recommend you use +a~glossary style such as \glostyle{altlist} with these acronym +styles to allow for the long name field. + +\item \acrstyle{short-long-desc}, \acrstyle{sc-short-long-desc}, +\acrstyle{sm-short-long-desc}: + +These styles are analogous to the above three styles, but the first +use display style is: +\begin{definition} +\cs{firstacronymfont}\marg{short} (\meta{long}) +\end{definition} +The definitions of \cs{acronymsort} and \cs{acronymentry} are the +same as those for \acrstyle{long-short-desc} etc. + +\item \acrstyle{dua}, \acrstyle{dua-desc}: + +These styles always display (via \ics{gls}) the long form regardless +of whether the entry has been used or not. However, \ics{acrfull} +and \ics{glsentryfull} will display \meta{long} (\cs{acronymfont}\marg{short}). In the case +of \acrstyle{dua}, the \gloskey{name} and \gloskey{sort} keys are set to +the short form and the description is set to the long form. In the +case of \acrstyle{dua-desc}, the \gloskey{name} and \gloskey{sort} +keys are set to the long form and the description is supplied in the +optional argument of \ics{newacronym}. + +\item \acrstyle{footnote}, \acrstyle{footnote-sc}, +\acrstyle{footnote-sm}: + +These three styles set the first use display to: +\begin{definition} +\cs{firstacronymfont}\marg{short}\ics{footnote}\marg{long} +\end{definition} +However, \ics{acrfull} and \ics{glsentryfull} are set to \cs{acronymfont}\marg{short} +(\meta{long}). (And similarly for plural and upper case forms.) +On subsequent use the display is: +\begin{definition} +\cs{acronymfont}\marg{short} +\end{definition} +The \gloskey{sort} and \gloskey{name} keys are set to +the short form, and the \gloskey{description} is set to the long +form. \begin{important} -Remember to load a package that defines \ics{textsmaller} (such as -\sty{relsize}) if you want to use this option, unless you want -to redefine \ics{acronymfont} to use some other formatting command. +In order to avoid nested hyperlinks on \firstuse\ the footnote +styles automatically implement \pkgopt[false]{hyperfirst}. \end{important} -\item[None of the above]\ifpdf \mbox{}\par\fi -If none of the package options \pkgopt{smallcaps}, \pkgopt{smaller}, -\pkgopt{footnote}, \pkgopt{dua} or \pkgopt{description} are used, -then on \firstuse\ the entry is displayed as: -\begin{display} -\meta{long} (\meta{abbrv})\meta{insert} -\end{display} -while subsequent use displays the entry as: -\begin{display} -\meta{abbrv}\meta{insert} -\end{display} -Entries will be sorted according to the short form. -\end{description} +\item \acrstyle{footnote-desc}, \acrstyle{footnote-sc-desc}, +\acrstyle{footnote-sm-desc}: -\section{Displaying the List of Acronyms} -\label{sec:disploa} +These three styles are similar to the previous three styles, but the +description has to be supplied in the optional argument of +\ics{newacronym}. The \gloskey{name} key is set to the long form +followed by the short form in parentheses and the \gloskey{sort} key +is set to the long form. This means that the acronyms will be sorted +according to the long form. In addition, since the \gloskey{name} +will typically be quite wide it's best to choose a glossary style +that can accommodate this, such as \glostyle{altlist}. -The list of acronyms is just like any other type of glossary and can -be displayed on its own using -\begin{alltt} -\ics{printglossary}[type=\ics{acronymtype}] -\end{alltt} -or with all the other -glossaries using \ics{printglossaries}. (If you use the -\pkgopt{acronym} package option you can also use -\begin{alltt} -\ics{printacronyms}\oarg{options} -\end{alltt} -as a synonym for -\begin{alltt} -\ics{printglossary}[type=\ics{acronymtype},\meta{options}] -\end{alltt} -See \sectionref{sec:pkgopts-acronym}.) +\end{itemize} -However, care must be taken to choose a glossary style that's -appropriate to your acronym style. The different acronym-related -package options store different information in the \gloskey{name}, -\gloskey{description} and \gloskey{symbol} keys. - -\Tableref{tab:acronymsettings} lists the package options that govern -the acronym styles and how the information is stored in the keys -used when displaying the glossary. Note that the \pkgopt{description} -package option uses the following command in the \gloskey{name}: -\begin{definition}[\DescribeMacro{\acrnameformat}] -\cs{acrnameformat}\marg{abbrv}\marg{long} -\end{definition} -This defaults to just \cs{acronymfont}\marg{abbrv}. - -For example, if I use the package options \pkgopt{description} and -\pkgopt{footnote}, then the name field will contain the abbreviation -and the symbol field will contain the long form. If I then use the -\glostyle{long4col} style, each entry in the list of acronyms will -appear in the form: -\begin{display} -\ics{acronymfont}\marg{abbrv} \meta{description} \meta{long} \meta{location list} -\end{display} -Alternatively, you can define your own custom style (see -\sectionref{sec:newglossarystyle} for further details). +\begin{example}{Adapting a Predefined Acronym Style}{ex:acrstyle} +Suppose I~want to use the \acrstyle{footnote-sc-desc} style, but +I~want the \gloskey{name} key set to the short form followed by the +long form in parentheses and the \gloskey{sort} key set to the short +form. Then I need to specify the \acrstyle{footnote-sc-desc} style: +\begin{verbatim} +\setacronymstyle{footnote-sc-desc} +\end{verbatim} +and then redefine \ics{acronymsort} and \ics{acronymentry}: +\begin{verbatim} +\renewcommand*{\acronymsort}[2]{#1}% sort by short form +\renewcommand*{\acronymentry}[1]{% + \acronymfont{\glsentryshort{#1}}\space (\glsentrylong{#1})}% +\end{verbatim} +(I've used \cs{space} for extra clarity, but you can just use an +actual space instead.) -\begin{table}[htbp] -\caption{Package options governing \cs{newacronym} and how the -information is stored} -\label{tab:acronymsettings} -\begin{center} -\begin{tabular}{lllll} -\bfseries Package Option & -\gloskey{name} & -\gloskey{description} & -\gloskey{symbol}\\ -\pkgopt{description},\pkgopt{footnote} & -\ics{acronymfont}\marg{abbrv} & -custom & -\meta{long}\\ -\pkgopt{description},\pkgopt{dua} & -\meta{long} & -custom & -\meta{abbrv}\\ -\pkgopt{description} & -\ics{acrnameformat}\marg{abbrv}\marg{long} & -custom & -\meta{abbrv}\\ -\pkgopt{footnote} & -\ics{acronymfont}\marg{abbrv} & -\meta{long} & - \\ -\pkgopt{smallcaps} & -\ics{acronymfont}\marg{abbrv} & -\meta{long} & -\meta{abbrv}\\ -\pkgopt{smaller} & -\ics{acronymfont}\marg{abbrv} & -\meta{long} & -\meta{abbrv}\\ -\pkgopt{dua} & -\meta{abbrv} & -\meta{long} & -\meta{abbrv}\\ -None of the above& -\meta{abbrv} & -\meta{long} & -\end{tabular} -\end{center} -\end{table} +Since the default Computer Modern fonts don't support bold +smallcaps, I'm also going to redefine \ics{acronymfont} so that it +always switches to medium weight to ensure the smallcaps setting is +used: +\begin{verbatim} +\renewcommand*{\acronymfont}[1]{\textmd{\scshape #1}} +\end{verbatim} +This isn't necessary if you use a font that supports bold smallcaps. -\section{Defining A Custom Acronym Style} +The sample file \samplefile{FnAcrDesc} illustrates this +example. +\end{example} + +\subsection{Defining A Custom Acronym Style} \label{sec:customacronym} You may find that the predefined acronyms styles that come with the \styfmt{glossaries} package don't suit your requirements. In this -case you can define your own style. This is done by redefining the -following commands: -\begin{definition}[\DescribeMacro{\CustomAcronymFields}] -\cs{CustomAcronymFields} -\end{definition} -This command sets up the keys for \ics{newglossaryentry} when -you define an acronym using \ics{newacronym}. Within the definition -of \cs{CustomAcronymFields}, you may use \cs{the}\ics{glslongtok} to -access the long form, \cs{the}\ics{glsshorttok} to access the short -form and \cs{the}\ics{glslabeltok} to access the label. This command -is typically used to set the \gloskey{name}, \gloskey{first}, -\gloskey{firstplural}, \gloskey{text} and \gloskey{plural} keys. It -may also be used to set the \gloskey{symbol} or -\gloskey{description} keys depending on your requirements. - -\begin{definition}[\DescribeMacro{\SetCustomDisplayStyle}] -\cs{SetCustomDisplayStyle}\marg{type} -\end{definition} -This is used to set up the display style for the glossary given by -\meta{type}. This should typically just use \ics{defglsentryfmt}. - -Once you have redefined \cs{CustomAcronymFields} and -\linebreak\cs{SetCustomDisplayStyle}, you must then switch to this style using -\begin{definition}[\DescribeMacro{\SetCustomStyle}] -\cs{SetCustomStyle} -\end{definition} -Note that you may still use the \pkgopt{shortcuts} package option -with your custom style. - -\begin{important} -If you omit \cs{SetCustomStyle}, or use it before you redefine -\cs{CustomAcronymFields} and \cs{SetCustomDisplayStyle}, your new -style won't be correctly implemented. You must set up the custom style -before defining new acronyms. The acronyms must be defined using -\ics{newacronym} not \ics{newglossaryentry} if you want to use -acronym styles. -\end{important} +case you can define your own style using: +\begin{definition}[\DescribeMacro{\newacronymstyle}] +\cs{newacronymstyle}\marg{style name}\marg{display}\marg{definitions} +\end{definition} +where \meta{style name} is the name of the new style (avoid active +characters). The second argument, \meta{display}, is equivalent to +the mandatory argument of \ics{defglsentryfmt}. You can simply use +\ics{glsgenacfmt} or you can customize the display using commands +like \ics{ifglsused}, \ics{glsifplural} and \ics{glscapscase}. +(See \sectionref{sec:glsdisplay} for further details.) +If the style is likely to be used with a mixed glossary (that is entries in +that glossary are defined both with \ics{newacronym} and +\ics{newglossaryentry}) then you can test if the entry is an acronym +and use \ics{glsgenacfmt} if it is or \ics{glsgenentryfmt} if it +isn't. For example, the \acrstyle{long-short} style sets +\meta{display} as +\begin{verbatim} +\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}% +\end{verbatim} +(You can use \ics{ifglshasshort} instead of \ics{ifglshaslong} to +test if the entry is an acronym if you prefer.) + +The third argument, \meta{definitions}, can be used to redefine the +commands that affect the display style, such as \ics{acronymfont} +or, if \meta{display} uses \cs{glsgenacfmt}, \ics{genacrfullformat} +and its variants. + +Note that \ics{setacronymstyle} redefines \ics{glsentryfull} and +\ics{acrfullfmt} to use \ics{genacrfullformat} (and similarly for +the plural and upper case variants). If this isn't appropriate for the +style (as in the case of styles like \acrstyle{footnote} and +\acrstyle{dua}) \cs{newacronymstyle} should redefine these commands +within \meta{definitions}. + + +Within \cs{newacronymstyle}'s \meta{definitions} argument you +can also redefine +\begin{definition}[\DescribeMacro{\GenericAcronymFields}] +\cs{GenericAcronymFields} +\end{definition} +This is a list of additional fields to be set in \ics{newacronym}. +You can use the following token registers to access the entry label, +long form and short form: \DescribeMacro{\glslabeltok}\cs{glslabeltok}, +\DescribeMacro{\glslongtok}\cs{glslongtok} and +\DescribeMacro{\glsshorttok}\cs{glsshorttok}. As with all \TeX\ +registers, you can access their values by preceding the register +with \ics{the}. For example, the \acrstyle{long-short} style does: +\begin{verbatim} +\renewcommand*{\GenericAcronymFields}{% + description={\the\glslongtok}}% +\end{verbatim} +which sets the \gloskey{description} field to the long form of the +acronym whereas the \acrstyle{long-short-desc} style does: +\begin{verbatim} +\renewcommand*{\GenericAcronymFields}{}% +\end{verbatim} +since the description needs to be specified by the user. + +It may be that you want to define a new acronym style that's based +on an existing style. Within \meta{display} you can use +\par +\DescribeMacro{\GlsUseAcrEntryDispStyle} +\begin{definition} +\cs{GlsUseAcrEntryDispStyle}\marg{style name} +\end{definition} +to use the \meta{display} definition from the style given by +\meta{style name}. Within \meta{definitions} you can use +\begin{definition}[\DescribeMacro{\GlsUseAcrStyleDefs}] +\cs{GlsUseAcrStyleDefs}\marg{style name} +\end{definition} +to use the \meta{definitions} from the style given by \meta{style +name}. For example, the \acrstyle{long-sc-short} acronym style is +based on the \acrstyle{long-short} style with minor +modifications (remember to use \verb|##| instead of \verb|#| within +\meta{definitions}): +\begin{verbatim} +\newacronymstyle{long-sc-short}% +{% use the same display as "long-short" + \GlsUseAcrEntryDispStyle{long-short}% +}% +{% use the same definitions as "long-short" + \GlsUseAcrStyleDefs{long-short}% + % Minor modifications: + \renewcommand{\acronymfont}[1]{\textsc{##1}}% + \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}% +} +\end{verbatim} +(\DescribeMacro{\glstextup}\cs{glstextup} is used to cancel the effect +of \ics{textsc}. This defaults to \ics{textulc}, if defined, +otherwise \ics{textup}. For example, the plural of \textsc{svm} +should be rendered as \textsc{svm}s rather than \textsc{svms}.) \begin{example}{Defining a Custom Acronym Style}{ex:customacrstyle} -Suppose I want my acronym on \gls{firstuse} to have the +Suppose I want my acronym on \firstuse\ to have the short form in the text and the long form with the description in a footnote. Suppose also that I want the short form to be put in small caps in the main body of the document, but I want it in normal @@ -5797,47 +6015,283 @@ form: \meta{long} (\meta{short}) \meta{description} \end{display} -First, I need to redefine \ics{CustomAcronymFields} so that -\linebreak\ics{newacronym} will correctly set the \gloskey{name}, -\gloskey{text} and \gloskey{plural} keys. I want the long form to be -stored in the \gloskey{name} and the short form to be stored in -\gloskey{text}. In addition, I'm going to set the \gloskey{symbol} -to the short form in upper case so that it will appear in the list -of acronyms. (An alternative approach is to define a custom glossary -style that uses \ics{glsentryshort} to access the short form. See -\sectionref{sec:newglossarystyle} for further details). +Let's suppose it's possible that I may have a mixed glossary. I can +check this in the second argument of \ics{newacronymstyle} using: +\begin{verbatim} +\ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}% +\end{verbatim} +This will use \ics{glsgenentryfmt} if the entry isn't an acronym, +otherwise it will use \ics{glsgenacfmt}. The third argument +(\meta{definitions}) of +\ics{newacronymstyle} needs to redefine \ics{genacrfullformat} etc +so that the \firstuse\ displays the short form in the text with the +long form in a footnote followed by the description. This is done as +follows (remember to use \verb|##| instead of \verb|#|): +\begin{verbatim} + % No case change, singular first use: + \renewcommand*{\genacrfullformat}[2]{% + \firstacronymfont{\glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + % First letter upper case, singular first use: + \renewcommand*{\Genacrfullformat}[2]{% + \firstacronymfont{\Glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + % No case change, plural first use: + \renewcommand*{\genplacrfullformat}[2]{% + \firstacronymfont{\glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% + % First letter upper case, plural first use: + \renewcommand*{\Genplacrfullformat}[2]{% + \firstacronymfont{\Glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% +\end{verbatim} +If you think it inappropriate for the short form to be capitalised +at the start of a sentence you can change the above to: +\begin{verbatim} + % No case change, singular first use: + \renewcommand*{\genacrfullformat}[2]{% + \firstacronymfont{\glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + % No case change, plural first use: + \renewcommand*{\genplacrfullformat}[2]{% + \firstacronymfont{\glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% + \let\Genacrfullformat\genacrfullformat + \let\Genplacrfullformat\genplacrfullformat +\end{verbatim} +Another variation is to use \ics{Glsentrylong} and +\ics{Glsentrylongpl} in the footnote instead of \ics{glsentrylong} and +\ics{glsentrylongpl}. + +Now let's suppose that commands such as \ics{glsentryfull} and +\ics{acrfull} shouldn't +use a~footnote, but instead use the format: \meta{long} +(\meta{short}). +This means that the style needs to redefine \cs{glsentryfull}, +\ics{acrfullfmt} and their plural and upper case variants. +First, the non-linking commands: \begin{verbatim} -\renewcommand*{\CustomAcronymFields}{% - name={\the\glslongtok},% - symbol={\MakeTextUppercase{\the\glsshorttok}},% - text={\textsc{\the\glsshorttok}},% - plural={\textsc{\the\glsshorttok}\noexpand\acrpluralsuffix}% -} + \renewcommand*{\glsentryfull}[1]{% + \glsentrylong{##1}\space + (\acronymfont{\glsentryshort{##1}})% + }% + \renewcommand*{\Glsentryfull}[1]{% + \Glsentrylong{##1}\space + (\acronymfont{\glsentryshort{##1}})% + }% + \renewcommand*{\glsentryfullpl}[1]{% + \glsentrylongpl{##1}\space + (\acronymfont{\glsentryshortpl{##1}})% + }% + \renewcommand*{\Glsentryfullpl}[1]{% + \Glsentrylongpl{##1}\space + (\acronymfont{\glsentryshortpl{##1}})% + }% +\end{verbatim} +Now for the linking commands: +\begin{verbatim} + \renewcommand*{\acrfullfmt}[3]{% + \glslink[##1]{##2}{% + \glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + \renewcommand*{\Acrfullfmt}[3]{% + \glslink[##1]{##2}{% + \Glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + \renewcommand*{\ACRfullfmt}[3]{% + \glslink[##1]{##2}{% + \MakeTextUppercase{% + \glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + }% + \renewcommand*{\acrfullplfmt}[3]{% + \glslink[##1]{##2}{% + \glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + \renewcommand*{\Acrfullplfmt}[3]{% + \glslink[##1]{##2}{% + \Glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + \renewcommand*{\ACRfullplfmt}[3]{% + \glslink[##1]{##2}{% + \MakeTextUppercase{% + \glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + }% +\end{verbatim} +(This may cause problems with long hyperlinks, in which case adjust +the definitions so that, for example, only the short form is inside +the argument of \ics{glslink}.) + +The style also needs to redefine \ics{acronymsort} so that the +acronyms are sorted according to the long form: +\begin{verbatim} + \renewcommand*{\acronymsort}[2]{##2}% +\end{verbatim} +If you prefer them to be sorted according to the short form you can +change the above to: +\begin{verbatim} + \renewcommand*{\acronymsort}[2]{##1}% +\end{verbatim} +The acronym font needs to be set to \ics{textsc} and the plural +suffix adjusted so that the ``s'' suffix in the plural short form +doesn't get converted to smallcaps: +\begin{verbatim} + \renewcommand*{\acronymfont}[1]{\textsc{##1}}% + \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}% +\end{verbatim} +There are a number of ways of dealing with the format in the list of +acronyms. The simplest way is to redefine \ics{acronymentry} to the +long form followed by the upper case short form in parentheses: +\begin{verbatim} + \renewcommand*{\acronymentry}[1]{% + \Glsentrylong{##1}\space + (\MakeTextUppercase{\glsentryshort{##1}})}% \end{verbatim} +(I've used \ics{Glsentrylong} instead of \ics{glsentrylong} to +capitalise the name in the glossary.) -When using \ics{newacronym}, the short and long forms are stored in -the \gloskey{short} and \gloskey{long} keys, and the plural forms -are stored in \gloskey{shortplural} and \gloskey{longplural}. -So when I use \ics{defglsentryfmt}, I can use \ics{glsentrylong} to access -the long form. Recall from \sectionref{sec:glsdisplay}, that the -optional argument to \ics{defglsentryfmt} indicates the glossary type. -This is passed to \ics{SetCustomDisplayStyle}. +An alternative approach is to set \ics{acronymentry} to just the +long form and redefine \ics{GenericAcronymFields} to set the +\gloskey{symbol} key to the short form and use a glossary style that +displays the symbol in parentheses after the \gloskey{name} (such as +the \glostyle{tree} style) like this: \begin{verbatim} -\renewcommand*{\SetCustomDisplayStyle}[1]{% - \defglsentryfmt[#1]{\glsgenentryfmt - \ifglsused{\glslabel}% test if entry has been used - {}% - {\footnote{\glsentrylong{\glslabel}}}}% + \renewcommand*{\acronymentry}[1]{\Glsentrylong{##1}}% + \renewcommand*{\GenericAcronymFields}{% + symbol={\protect\MakeTextUppercase{\the\glsshorttok}}}% +\end{verbatim} +I'm going to use the first approach and set +\ics{GenericAcronymFields} to do nothing: +\begin{verbatim} + \renewcommand*{\GenericAcronymFields}{}% +\end{verbatim} + +Finally, this style needs to switch off hyperlinks on first use to +avoid nested links: +\begin{verbatim} + \glshyperfirstfalse +\end{verbatim} +Putting this all together: +\begin{verbatim} +\newacronymstyle{custom-fn}% new style name +{% + \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}% +}% +{% + \renewcommand*{\GenericAcronymFields}{}% + \glshyperfirstfalse + \renewcommand*{\genacrfullformat}[2]{% + \firstacronymfont{\glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + \renewcommand*{\Genacrfullformat}[2]{% + \firstacronymfont{\Glsentryshort{##1}}##2% + \footnote{\glsentrylong{##1}: \glsentrydesc{##1}}% + }% + \renewcommand*{\genplacrfullformat}[2]{% + \firstacronymfont{\glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% + \renewcommand*{\Genplacrfullformat}[2]{% + \firstacronymfont{\Glsentryshortpl{##1}}##2% + \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}% + }% + \renewcommand*{\glsentryfull}[1]{% + \glsentrylong{##1}\space + (\acronymfont{\glsentryshort{##1}})% + }% + \renewcommand*{\Glsentryfull}[1]{% + \Glsentrylong{##1}\space + (\acronymfont{\glsentryshort{##1}})% + }% + \renewcommand*{\glsentryfullpl}[1]{% + \glsentrylongpl{##1}\space + (\acronymfont{\glsentryshortpl{##1}})% + }% + \renewcommand*{\Glsentryfullpl}[1]{% + \Glsentrylongpl{##1}\space + (\acronymfont{\glsentryshortpl{##1}})% + }% + \renewcommand*{\acrfullfmt}[3]{% + \glslink[##1]{##2}{% + \glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + \renewcommand*{\Acrfullfmt}[3]{% + \glslink[##1]{##2}{% + \Glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + \renewcommand*{\ACRfullfmt}[3]{% + \glslink[##1]{##2}{% + \MakeTextUppercase{% + \glsentrylong{##2}##3\space + (\acronymfont{\glsentryshort{##2}})% + }% + }% + }% + \renewcommand*{\acrfullplfmt}[3]{% + \glslink[##1]{##2}{% + \glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + \renewcommand*{\Acrfullplfmt}[3]{% + \glslink[##1]{##2}{% + \Glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + \renewcommand*{\ACRfullplfmt}[3]{% + \glslink[##1]{##2}{% + \MakeTextUppercase{% + \glsentrylongpl{##2}##3\space + (\acronymfont{\glsentryshortpl{##2}})% + }% + }% + }% + \renewcommand*{\acronymfont}[1]{\textsc{##1}}% + \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}% + \renewcommand*{\acronymsort}[2]{##2}% + \renewcommand*{\acronymentry}[1]{% + \Glsentrylong{##1}\space + (\MakeTextUppercase{\glsentryshort{##1}})}% } \end{verbatim} -Now that I've redefined \ics{CustomAcronymFields} and -\linebreak\ics{SetCustomDisplayStyle}, I can set this style using +Now I need to specify that I want to use this new style: +\begin{verbatim} +\setacronymstyle{custom-fn} +\end{verbatim} +I also need to use a glossary style that suits this acronym style, +for example \glostyle{altlist}: \begin{verbatim} -\SetCustomStyle +\setglossarystyle{altlist} \end{verbatim} -and now I can define my acronyms: + +Once the acronym style has been set, I can define my acronyms: \begin{verbatim} \newacronym[description={set of tags for use in developing hypertext documents}]{html}{html}{Hyper @@ -5848,29 +6302,35 @@ layout of a document written in a markup language}]{css} {css}{Cascading Style Sheet} \end{verbatim} -If I want to use the \sty{hyperref} package with this document, -it can cause a problem on \gls{firstuse} as I'll get nested -hyperlinks, so I need to switch off the hyperlinks on \gls{firstuse} -via the package option \pkgopt[false]{hyperfirst}. In addition, I -want to use a glossary style that displays the symbol. Therefore, in -my preamble I have: - -\begin{verbatim} -\usepackage[colorlinks]{hyperref} -\usepackage - [acronym, % create list of acronyms - nomain, % don't need main glossary for this example - style=tree, % need a style that displays the symbol - hyperfirst=false% don't hyperlink first use - ]{glossaries} -\end{verbatim} - -Note that I haven't used the \pkgopt{description} or -\pkgopt{footnote} package options. The sample file \samplefile{-custom-acronym} illustrates this example. \end{example} +\section{Displaying the List of Acronyms} +\label{sec:disploa} + +The list of acronyms is just like any other type of glossary and can +be displayed on its own using +\begin{alltt} +\ics{printglossary}[type=\ics{acronymtype}] +\end{alltt} +or with all the other +glossaries using \ics{printglossaries}. (If you use the +\pkgopt{acronym} package option you can also use +\begin{alltt} +\ics{printacronyms}\oarg{options} +\end{alltt} +as a synonym for +\begin{alltt} +\ics{printglossary}[type=\ics{acronymtype},\meta{options}] +\end{alltt} +See \sectionref{sec:pkgopts-acronym}.) + +However, care must be taken to choose a glossary style that's +appropriate to your acronym style. +Alternatively, you can define your own custom style (see +\sectionref{sec:newglossarystyle} for further details). + \section{Upgrading From the glossary Package} \label{sec:oldacronym} @@ -5953,12 +6413,10 @@ optional argument from being recognised. \par \end{table} - - \chapter{Unsetting and Resetting Entry Flags} \label{sec:glsunset} -When using \ics{gls}, \ics{glspl} and their uppercase variants it is +When using \ics{gls}, \ics{glspl} and their upper case variants it is possible that you may want to use the value given by the \gloskey{first} key, even though you have already \glslink{firstuse}{used} the glossary entry. Conversely, you may want to use the value given by the @@ -6007,6 +6465,62 @@ where \meta{label} is the label of the required entry. If the entry has been used, \meta{true part} will be done, otherwise \meta{false part} will be done. +\begin{important} +Be careful when using commands such as \ics{gls} within an +environment or command argument that gets processed multiple times +as it can cause unwanted side-effects when the first use displayed +text is different from subsequent use. +\end{important} + +For example, the \env{frame} environment in \cls{beamer} processes +its argument for each overlay. This means that the \firstuseflag\ +will be unset on the first overlay and subsequent overlays will use +the non-first use form. + +Consider the following example: +\begin{verbatim} +\documentclass{beamer} + +\usepackage{glossaries} + +\newacronym{svm}{SVM}{support vector machine} + +\begin{document} + +\begin{frame} + \frametitle{Frame 1} + + \begin{itemize} + \item<+-> \gls{svm} + \item<+-> Stuff. + \end{itemize} +\end{frame} + +\end{document} +\end{verbatim} + +On the first overlay, \verb|\gls{svm}| produces ``support vector +machine (SVM)'' and then unsets the \firstuseflag. When the second +overlay is processed, \verb|\gls{svm}| now produces ``SVM'', which +is unlikely to be the desired effect. I~don't know anyway around +this and the only suggestion I~can give is to explicitly reset each +acronym on first use: +\begin{verbatim} +\begin{frame} + \frametitle{Frame 1} + + \begin{itemize} + \item<+-> \glsreset{svm}\gls{svm} + \item<+-> Stuff. + \end{itemize} +\end{frame} +\end{verbatim} +This is non-optimal, but the \cls{beamer} class is too complex for +me to suggest an alternative solution. + +The \sty{amsmath} environments, such as \env{align}, also process +their contents multiple times, but the \styfmt{glossaries} package now +checks for this. \chapter{Glossary Styles} \label{sec:styles} |