summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-04-17 00:12:13 +0000
committerKarl Berry <karl@freefriends.org>2009-04-17 00:12:13 +0000
commit4050d85ba1394b75a677598fc1072a789001ceef (patch)
tree526f84414346a5021563bdeb2916de248be6eb63 /Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
parenta59811571ec98d9930b16db1213daf261e6eed78 (diff)
glossaries 1.2 (16apr09)
git-svn-id: svn://tug.org/texlive/trunk@12738 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex528
1 files changed, 280 insertions, 248 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
index b72457ec914..9791f8f8b72 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
@@ -131,7 +131,7 @@
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{glossaries.sty v 1.19: \LaTeXe\ Package to Assist Generating Glossaries}
+ \title{glossaries.sty v 1.2: \LaTeXe\ Package to Assist Generating Glossaries}
\author{Nicola L.C. Talbot\\[10pt]
School of Computing Sciences\\
University of East Anglia\\
@@ -139,7 +139,7 @@ Norwich. Norfolk\\
NR4 7TJ. United Kingdom.\\
\url{http://theoval.cmp.uea.ac.uk/~nlct/}}
- \date{2nd March 2009}
+ \date{16th April 2009}
\maketitle
\tableofcontents
@@ -1129,11 +1129,44 @@ of how to get started. However it is recommended that you read
for additional commands and advice not listed here. There are
also some sample files to help you get started, listed in
\ifmakedtx{\autoref{sec:samples}}{\htmlref{Sample
-Documents}{sec:samples}}.
+Documents}{sec:samples}}. The following is a minimal example:
+\begin{verbatim}
+ \documentclass{article}
+ % Load hyperref before glossaries
+ \usepackage[colorlinks]{hyperref}
+ \usepackage[acronym, % make a separate list of acronyms
+ toc % put the glossaries into the table of contents
+ ]{glossaries}
-\begin{enumerate}
-\item Load \sty{glossaries} \emph{after} \isty{hyperref}:
+ % Write glossary entries to external file so that they
+ % can be sorted and collated by another application.
+ \makeglossaries
+
+ % Define an entry whose label is `xample':
+ \newglossaryentry{xample}% unique label identifying this entry
+ {% Define the attributes for this entry:
+ name=sample,% the name or term begin defined
+ description={a sample entry}% a description of this entry
+ }
+
+ % Define an acronym whose label is `ca':
+ \newacronym{ca}% label
+ {CA}% acronym
+ {Contrived Acronym}% expanded form
+
+ \begin{document}
+ \tableofcontents
+
+ A \gls{xample} entry and a \gls{ca}.
+
+ \printglossaries
+ \end{document}
+\end{verbatim}
+\ifmakedtx{}{\toTop}
+
+\subsection{Package Order}
+Load \sty{glossaries} \emph{after} \isty{hyperref}:
\begin{verbatim}
\usepackage{hyperref}
\usepackage{glossaries}
@@ -1143,8 +1176,21 @@ Similarly for the \isty{html} package:
\usepackage{html}
\usepackage{glossaries}
\end{verbatim}
+Likewise for \isty{babel} and \isty{translator}.
-\item Always use \ics{makeglossaries} if you want the glossary
+Note that if you are using the \isty{hyperref} package and the
+glossaries are in chapters, you may need to redefine
+\ics{glsclearpage} to do \ics{clearpage} instead of
+\cs{cleardoublepage} to prevent an unwanted blank page appearing
+before the glossary:
+\begin{verbatim}
+\renewcommand*{\glsclearpage}{\clearpage}
+\end{verbatim}
+\ifmakedtx{}{\toTop}
+
+\subsection{Displaying Glossaries}
+
+Always use \ics{makeglossaries} if you want the glossary
entries to be written to the glossary file:
\begin{verbatim}
\usepackage{glossaries}
@@ -1153,7 +1199,7 @@ entries to be written to the glossary file:
If you don't use \ics{makeglossaries}, your glossaries will
not appear in the document!
-\item Use \ics{printglossaries} to make your glossaries appear
+Use \ics{printglossaries} to make your glossaries appear
in the document at that point. For example:
\begin{verbatim}
\maketitle
@@ -1162,8 +1208,81 @@ in the document at that point. For example:
\end{verbatim}
Note that only the glossary entries that have been used in the
document text will appear in the glossary.
+See \ifmakedtx{\autoref{sec:printglossary}}{\htmlref{Displaying a glossary}{sec:printglossary} in the main overview section}
+for further details.
+
+To add the glossaries to the table of contents use the
+\pkgopt{toc} package option:
+\begin{verbatim}
+\usepackage[toc]{glossaries}
+\end{verbatim}
+This will require an extra \LaTeX\ run. Note that if the table
+of contents affects the subsequent page numbering (i.e.\ the
+page numbers are not reset after the table of contents) then you
+may need to rerun \appname{makeglossaries} and \LaTeX.
-\item When you have created your document, run \LaTeX\ on it,
+The font used to display the entry name in the glossary
+is governed by \ics{glsnamefont}. This can be redefined
+as required. For example, to make the entry names appear
+in a medium sans-serif font do:
+\begin{verbatim}
+\renewcommand{\glsnamefont}[1]{\textsf{\mdseries #1}}
+\end{verbatim}
+Note that the list-like glossary styles place the entry name in
+the optional argument to \ics{item}, so they will
+appear in bold, unless you redefine \ics{glsnamefont} to counteract
+the bold font. Similarly, the tree-like styles display the
+entry name in bold.
+
+Glossary styles can be set using the \pkgopt{style}
+package option. For example:
+\begin{verbatim}
+\usepackage[style=long3col]{glossaries}
+\end{verbatim}
+or using \ics{glossarystyle}\marg{style}. For example:
+\begin{verbatim}
+\glossarystyle{altlist}
+\end{verbatim}
+The predefined glossary styles provided by the \sty{glossaries}
+bundle are listed in \ifmakedtx{\autoref{sec:styles}}{\htmlref{{Glossary
+Styles}}{sec:styles}}.
+
+Each entry in the glossary has an associated list of numbers
+indicating whereabouts in the document that entry has been used.
+The number lists can be suppressed using package option
+\pkgopt{nonumberlist}:
+\begin{verbatim}
+\usepackage[nonumberlist]{glossaries}
+\end{verbatim}
+See \ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number lists}{sec:numberlists}}
+for further details about number lists.
+
+If your pages have a hyphen compositor (i.e.\ your page
+numbers appear in the form 2-1), use \ics{glsSetCompositor}
+\emph{before} \ics{makeglossaries}:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\glsSetCompositor{-}
+\makeglossaries
+\end{verbatim}
+
+By default, the glossary will appear in an unnumbered
+chapter if chapters are defined, otherwise in an unnumbered
+section. This can be changed using the \pkgopt{section} package
+option. For example, to make the glossaries appear in an unnumbered
+section, even if chapters are defined, do:
+\begin{verbatim}
+\usepackage[section]{glossaries}
+\end{verbatim}
+Other sectional units can also be specified as
+\pkgopt{section}=\meta{value}. For example, to make the glossaries
+appear in unnumbered subsections:
+\begin{verbatim}
+\usepackage[section=subsection]{glossaries}
+\end{verbatim}
+
+When you have created your document, run \LaTeX\ on it,
then the Perl script \appname{makeglossaries}, then run \LaTeX\
on it again:
\begin{verbatim}
@@ -1185,7 +1304,7 @@ still need Perl installed. Alternatively, you can call
Associated Glossary Files}{sec:makeglossaries}} for
further details.
-\item If you want to use \appname{xindy} instead of
+If you want to use \appname{xindy} instead of
\appname{makeindex}, you must specify it in the package option:
\begin{verbatim}
\usepackage[xindy]{glossaries}
@@ -1194,8 +1313,11 @@ See
\ifmakedtx{\autoref{sec:makeglossaries}}{\htmlref{Generating the
Associated Glossary Files}{sec:makeglossaries}} for
further details.
+\ifmakedtx{}{\toTop}
-\item New glossaries can be defined using:\par
+\subsection{Defining Additional Glossaries}
+
+New glossaries can be defined using:\par
\ics{newglossary}\oarg{log-ext}%
\marg{label}\marg{in-ext}\marg{out-ext}%
\marg{title}\par where \meta{label} is an identifying label,
@@ -1216,7 +1338,7 @@ will be Notation. If you use \appname{makeglossaries}, the
extension \filetype{.nlg}. If \meta{log-ext} is omitted, the extension
\filetype{.glg} will be used.
-\item Any new glossaries must be defined before
+Any new glossaries must be defined before
\ics{makeglossaries}:
\begin{verbatim}
\usepackage{glossaries}
@@ -1224,35 +1346,18 @@ extension \filetype{.nlg}. If \meta{log-ext} is omitted, the extension
\makeglossaries
\end{verbatim}
-\item If you use the \pkgopt{acronym} package option, the
+If you use the \pkgopt{acronym} package option, the
\sty{glossaries} package
will automatically create a new glossary type labelled
\texttt{acronym}:
\begin{verbatim}
\usepackage[acronym]{glossaries}
\end{verbatim}
+\ifmakedtx{}{\toTop}
-\item If your pages have a hyphen compositor (i.e.\ your page
-numbers appear in the form 2-1), use \ics{glsSetCompositor}
-\emph{before} \ics{makeglossaries}:
-\begin{verbatim}
-\documentclass{article}
-\usepackage{glossaries}
-\glsSetCompositor{-}
-\makeglossaries
-\end{verbatim}
-
-\item To add the glossaries to the table of contents use the
-\pkgopt{toc} package option:
-\begin{verbatim}
-\usepackage[toc]{glossaries}
-\end{verbatim}
-This will require an extra \LaTeX\ run. Note that if the table
-of contents affects the subsequent page numbering (i.e.\ the
-page numbers are not reset after the table of contents) then you
-may need to rerun \appname{makeglossaries} and \LaTeX.
+\subsection{Defining New Entries}
-\item Define a new entry with:\par
+A glossary term is defined using:\par
\ics{newglossaryentry}\marg{label}\marg{key-val list}\par
The \meta{key-val list} must at least contain a \gloskey{name}
key and a \gloskey{description} key.
@@ -1265,45 +1370,63 @@ In this example, I have given the entry the label \texttt{perl}.
Whenever I want to use this entry, that is the label I need
to use to identify it.
-\item To define a sub-entry, use the \gloskey{parent} key. For
-example:
+Only those terms that have actually been used in the
+document will be placed in the glossary. If you have defined
+a term that doesn't appear in the glossary, then it means
+you haven't used it in the text (either via \ics{glslink}
+or \ics{gls} and related commands or via \ics{glsadd}
+or \ics{glsaddall} or via \ics{glssee}).
+
+If you have multiple glossaries, use the \gloskey{type}
+key to specify in which glossary the entry belongs. For example:
\begin{verbatim}
-\newglossaryentry{fruit}{name={fruit}, % parent entry
-description={tree product that contains seeds}}
+\newglossary{languages}{lan}{lng}{Index of Languages}
-\newglossaryentry{apple}{name={apple}, % sub-entry
-description={firm, round fruit},
-parent=fruit}
+\makeglossaries
+
+\newglossaryentry{perl}{name=Perl,
+description=A scripting language,
+type=languages}
\end{verbatim}
+If \gloskey{type} is omitted, the default glossary is used.
-\item To change the sorting order, use the \gloskey{sort} key.
+Remember to group values that have a comma or equal sign.
For example:
\begin{verbatim}
-\newglossaryentry{tex}{name={\TeX},
-description={A typesetting language},
-sort=tex}
+\newglossaryentry{pagelist}{name=page list,
+description={A list of individual pages or page ranges
+(e.g.\ 1,2,4,7--9)}}
\end{verbatim}
-This will put the entry in the \dq{T} group (entries starting with
-the letter \dq{t} or \dq{T}) rather than the
-\dq{symbols} group (entries starting with a symbol).
-Similarly, the following example puts the entry in the \dq{U}
-group instead of the \dq{symbol} group.
+
+Associated symbols can also be specified, but whether the
+symbol appears in the glossary depends on the glossary style.
+For example:
\begin{verbatim}
-\newglossaryentry{universal}{name={\ensuremath{\mathcal{U}}},
-description=The universal set,
-sort=U}
+\newglossaryentry{metre}{name={metre},
+description={A metric measurement of length},
+symbol={m}}
\end{verbatim}
+See \ifmakedtx{\autoref{sec:styles}}{\htmlref{Glossary
+Styles}{sec:styles}} for a list of predefined glossary
+styles.
+
+See \ifmakedtx{\autoref{sec:newglosentry}}{\htmlref{Defining Glossary Entries}{sec:newglosentry} in the main overview section}
+for further details.
+\ifmakedtx{}{\toTop}
-Note that if you use \appname{xindy} instead of \appname{makeindex},
-characters such as a backslash are ignored, so if you have used
-the \pkgopt{xindy} package option, you can just do:
+\subsection{Defining Sub-Entries}
+To define a sub-entry, use the \gloskey{parent} key. For
+example:
\begin{verbatim}
-\newglossaryentry{tex}{name={\TeX},
-description={A typesetting language},
-}
+\newglossaryentry{fruit}{name={fruit}, % parent entry
+description={tree product that contains seeds}}
+
+\newglossaryentry{apple}{name={apple}, % sub-entry
+description={firm, round fruit},
+parent=fruit}
\end{verbatim}
-\item Sub-entries may have the same name as the parent entry:
+Sub-entries may have the same name as the parent entry:
\begin{verbatim}
\newglossaryentry{glossary}{name=glossary, % parent entry
description={\nopostdesc},
@@ -1325,7 +1448,45 @@ needed to sort the sub-entries. The parent entry has no
description, so the description terminator is suppressed using
\ics{nopostdesc}.
-\item If the entry name starts with an accented letter or
+See \ifmakedtx{\autoref{sec:subentries}}{\htmlref{Sub-Entries}{sec:subentries}} for
+further details.
+\ifmakedtx{}{\toTop}
+
+\subsection{Changing the Sort Order}
+To change the sorting order, use the \gloskey{sort} key.
+For example:
+\begin{verbatim}
+\newglossaryentry{tex}{name={\TeX},
+description={A typesetting language},
+sort=tex}
+\end{verbatim}
+This will put the entry in the \dq{T} group (entries starting with
+the letter \dq{t} or \dq{T}) rather than the
+\dq{symbols} group (entries starting with a symbol).
+Similarly, the following example puts the entry in the \dq{U}
+group instead of the \dq{symbol} group.
+\begin{verbatim}
+\newglossaryentry{universal}{name={\ensuremath{\mathcal{U}}},
+description=The universal set,
+sort=U}
+\end{verbatim}
+
+Unlike the old \sty{glossary} package, you don't need to escape
+\appname{makeindex}'s special characters:
+\begin{verbatim}
+\newglossaryentry{quote}{name={"},
+description={Double quote character}}
+
+\newglossaryentry{exclam}{name={!},
+description={Exclamation mark}}
+
+\newacronym{rna}{RNA}{ribonukleins\"aure}
+\end{verbatim}
+
+\ifmakedtx{}{\toTop}
+
+\subsection{Accented or Non-Latin Characters}
+If the entry name starts with an accented letter or
non-Latin character, you will need to group the first letter
(otherwise it will cause a problem for commands like \ics{Gls} and
\ics{Glspl}):
@@ -1342,7 +1503,7 @@ sort=oesophagus,
description={canal from mouth to stomach}}
\end{verbatim}
-\item If you use \appname{xindy}, you can specify the accented
+If you use \appname{xindy}, you can specify the accented
or non-Latin character directly (in combination with the
\isty{inputenc} and \isty{fontenc} packages) but you still
need to group the first letter (otherwise it will cause a
@@ -1354,29 +1515,10 @@ description={select group or class}}
\end{verbatim}
Note that in this case the \gloskey{sort} key is not required
as \appname{xindy} knows how to sort the letter \'e.
+\ifmakedtx{}{\toTop}
-\item If you have multiple glossaries, use the \gloskey{type}
-key to specify in which glossary the entry belongs. For example:
-\begin{verbatim}
-\newglossary{languages}{lan}{lng}{Index of Languages}
-
-\makeglossaries
-
-\newglossaryentry{perl}{name=Perl,
-description=A scripting language,
-type=languages}
-\end{verbatim}
-If \gloskey{type} is omitted, the default glossary is used.
-
-\item Remember to group values that have a comma or equal sign.
-For example:
-\begin{verbatim}
-\newglossaryentry{pagelist}{name=page list,
-description={A list of individual pages or page ranges
-(e.g.\ 1,2,4,7--9)}}
-\end{verbatim}
-
-\item You can cross-reference an entry using the
+\subsection{Cross-Referencing Entries}
+You can cross-reference an entry using the
\gloskey{see} key when you define it. For example, suppose
you have defined an entry whose label is \texttt{taylorstheorem},
then you can cross-reference it:
@@ -1396,8 +1538,10 @@ The \dq{see} tag may be overridden for a given entry:
\glssee[see also]{maclaurinseries}{taylorstheorem}
\end{verbatim}
or it can be changed for all entries by redefining \ics{seename}.
+\ifmakedtx{}{\toTop}
-\item Plural forms are assumed to be the singular form with an
+\subsection{Plurals}
+Plural forms are assumed to be the singular form with an
\dq{s} appended, unless otherwise specified. To specify an
irregular plural, use the \gloskey{plural} key. For example:
\begin{verbatim}
@@ -1406,7 +1550,7 @@ description=rectangular array of quantities,
plural=matrices}
\end{verbatim}
-\item The way the term appears in the main text can be different
+The way the term appears in the main text can be different
from the way the term appears in the glossary:
\begin{verbatim}
\newglossaryentry{matrix}{name=Matrix,
@@ -1416,65 +1560,18 @@ plural=matrices}
\end{verbatim}
In this example, the entry name appears as \dq{Matrix} in the
glossary, and either \dq{matrix} or \dq{matrices} in the text.
+\ifmakedtx{}{\toTop}
-\item The way the term appears on \firstuse\ can be different
-to the way it appears subsequently:
-\begin{verbatim}
-\newglossaryentry{singmtx}{name=Singular Matrix,
-description=A matrix with a zero determinant,
-first=singular matrix (SM),
-text=SM,
-firstplural=singular matrices (SMs)}
-\end{verbatim}
-In this example, the entry name appears as \dq{Singular Matrix} in
-the glossary, and in the text it appears as \dq{singular matrix (SM)}
-or \dq{singular matrices (SMs)} the first time the entry is used,
-and subsequently appears as \dq{SM} or \dq{SMs}.
-
-\item The quick and easy way to define an acronym is to use:\par
-\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrev}%
-\marg{long}\par
-For example:
-\begin{verbatim}
-\newacronym{svm}{SVM}{support vector machine}
-\end{verbatim}
-This is equivalent to:
-\begin{verbatim}
-\newglossaryentry{svm}{type=\acronymtype,
-name={SVM},
-description={support vector machine},
-text={SVM},
-first={support vector machine (SVM)},
-plural={SVMs},
-firstplural={support vector machines (SVMs)}}
-\end{verbatim}
-(The value of \ics{acronymtype} varies depending on whether
-the \pkgopt{acronym} package option is used or not.
-The optional argument \meta{key-val list} can be used to
-override any of the \ics{newglossaryentry} keys; for
-example, if the acronym has an irregular plural.)
-
-\item The font used to display the entry name in the glossary
-is governed by \ics{glsnamefont}. This can be redefined
-as required. For example, to make the entry names appear
-in a medium sans-serif font do:
-\begin{verbatim}
-\renewcommand{\glsnamefont}[1]{\textsf{\mdseries #1}}
-\end{verbatim}
-Note that the list-like glossary styles place the entry name in
-the optional argument to \ics{item}, so they will
-appear in bold, unless you redefine \ics{glsnamefont} to counteract
-the bold font. Similarly, the tree-like styles display the
-entry name in bold.
-
-\item In the document use \ics{gls}\marg{label}
-to use a predefined term (this will also enter the term into
+\subsection{Displaying Terms in the Document}
+In the document use \ics{gls}\marg{label}
+to use a term that has already been defined with
+\ics{newglossaryentry} (this will also enter the term into
the associated glossary output file). For example:
\begin{verbatim}
A \gls{singmtx} is a matrix with a zero determinant.
\end{verbatim}
-\item Other variations:
+Other variations:
\begin{itemize}
\item \ics{Gls}\marg{label} : like \cs{gls},
but with first letter in upper case
@@ -1494,51 +1591,25 @@ the first letter in uppercase:
\Glspl{singmtx} are matrices with a zero determinant.
\end{verbatim}
-\item Additional text can be appended to the link using the
+Additional text can be appended to the link using the
end optional argument. For example, to form the possessive:
\begin{verbatim}
The \gls{singmtx}['s] dimensions \ldots
\end{verbatim}
+See \ifmakedtx{\autoref{sec:glslink}}{\htmlref{Links to Glossary Entries}{sec:glslink}}
+for further details.
-\item The format of the associated entry number can be
-changed using the \gloskey[glslink]{format} key in the optional argument.
-Note that the value of the \gloskey[glslink]{format} key should be the
-name of a command \emph{without} the initial backslash. For
-example:
-\begin{verbatim}
-The primary definition of \glspl[format=textbf]{singmtx}.
-\end{verbatim}
-In this example the relevant glossary entry will have the
-page number in bold (since it uses \cs{textbf}) but
-it will no longer have a hyperlink (if hyperlinks are enabled).
-
-\item The \sty{glossaries} package provides commands to
-change the font whilst ensuring that the number remains a
-hyperlink. These are of the form \cs{hyper}\meta{xx} and
-are equivalent to the standard font changing commands of the
-form \cs{text}\meta{xx}, as well as \ics{hyperemph}
-(which uses \ics{emph}). For example:
-\begin{verbatim}
-The primary definition of \glspl[format=hyperbf]{singmtx}.
-\end{verbatim}
-
-\item Don't use declarations in \gloskey[glslink]{format} (e.g.\
-\texttt{format=bfseries}) as this can cause unpredictable results,
-since there is no guarantee that the effect will be localised to the
-required text.
-
-\item Entries can be added to the glossary without producing
+Entries can be added to the glossary without producing
any text using \ics{glsadd}\marg{label} or
-\ics{glsaddall}. These commands also take an optional
-argument where you can specify the format. For example
+\ics{glsaddall}. For example
\begin{verbatim}
-\glsadd[format=hyperbf]{singmtx}
+\glsadd{singmtx}
\end{verbatim}
will add a line to the
glossary file for the specified term, but will not produce
any text where the command occurs.
-\item A number range can be entered using \verb|format=(| and
+A number range can be entered using \verb|format=(| and
\verb"format=)" to mark the beginning and ending of the
range. For example:
\begin{verbatim}
@@ -1552,94 +1623,53 @@ range. For example:
This is equivalent to \appname{makeindex}'s \verb"|(" and \verb"|)"
formats or \appname{xindy}'s \texttt{:open-range} and
\texttt{:close-range} tags.
+\ifmakedtx{}{\toTop}
-\item You can combine the range markers with a formatting command
-(again without the preceding backslash). For example:
-\begin{verbatim}
- This is the start of a very long section all
- about \glspl[format=(hyperbf]{singmtx}.
-
- % lots of text omitted
-
- This is the end a very long section all about
- \glspl[format=)hyperbf]{singmtx}.
-\end{verbatim}
-
-\item Only those terms that have actually been used in the
-document will be placed in the glossary. If you have defined
-a term that doesn't appear in the document, then it means
-you haven't used it in the text (either via \ics{glslink}
-or \ics{gls} and related commands or via \ics{glsadd}
-or \ics{glsaddall} or via \ics{glssee}).
-
-\item You don't need to escape \appname{makeindex}'s special characters:
+\subsection{Acronyms}
+The way the term appears on \firstuse\ can be different
+to the way it appears subsequently:
\begin{verbatim}
-\newglossaryentry{quote}{name={"},
-description={Double quote character}}
-
-\newglossaryentry{exclam}{name={!},
-description={Exclamation mark}}
-
-\newacronym{rna}{RNA}{ribonukleins\"aure}
+\newglossaryentry{singmtx}{name=Singular Matrix,
+description=A matrix with a zero determinant,
+first=singular matrix (SM),
+text=SM,
+firstplural=singular matrices (SMs)}
\end{verbatim}
+In this example, the entry name appears as \dq{Singular Matrix} in
+the glossary, and in the text it appears as \dq{singular matrix (SM)}
+or \dq{singular matrices (SMs)} the first time the entry is used,
+and subsequently appears as \dq{SM} or \dq{SMs}.
-\item Associated symbols can also be specified, but whether the
-symbol appears in the glossary depends on the glossary style.
+The quick and easy way to define an acronym is to use:\par
+\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrev}%
+\marg{long}\par
For example:
\begin{verbatim}
-\newglossaryentry{metre}{name={metre},
-description={A metric measurement of length},
-symbol={m}}
-\end{verbatim}
-See \ifmakedtx{\autoref{sec:styles}}{\htmlref{Glossary
-Styles}{sec:styles}} for a list of predefined glossary
-styles.
-
-\item Glossary styles can be set using the \pkgopt{style}
-package option. For example:
-\begin{verbatim}
-\usepackage[style=long3col]{glossaries}
-\end{verbatim}
-or using \ics{glossarystyle}\marg{style}. For example:
-\begin{verbatim}
-\glossarystyle{altlist}
-\end{verbatim}
-The predefined glossary styles provided by the \sty{glossaries}
-bundle are listed in \ifmakedtx{\autoref{sec:styles}}{\htmlref{{Glossary
-Styles}}{sec:styles}}.
-
-
-\item The list of numbers associated with each glossary entry
-can be suppressed using the package option \pkgopt{nonumberlist}:
-\begin{verbatim}
-\usepackage[nonumberlist]{glossaries}
-\end{verbatim}
-
-\item By default, the glossary will appear in an unnumbered
-chapter if chapters are defined, otherwise in an unnumbered
-section. This can be changed using the \pkgopt{section} package
-option. For example, to make the glossaries appear in an unnumbered
-section, even if chapters are defined, do:
-\begin{verbatim}
-\usepackage[section]{glossaries}
-\end{verbatim}
-Other sectional units can also be specified as
-\pkgopt{section}=\meta{value}. For example, to make the glossaries
-appear in unnumbered subsections:
-\begin{verbatim}
-\usepackage[section=subsection]{glossaries}
+\newacronym{svm}{SVM}{support vector machine}
\end{verbatim}
-
-\item If you are using the \isty{hyperref} package and the
-glossaries are in chapters, you may need to redefine
-\ics{glsclearpage} to do \ics{clearpage} instead of
-\cs{cleardoublepage} to prevent an unwanted blank page appearing
-before the glossary:
+This is equivalent to:
\begin{verbatim}
-\renewcommand*{\glsclearpage}{\clearpage}
+\newglossaryentry{svm}{type=\acronymtype,
+name={SVM},
+description={support vector machine},
+text={SVM},
+first={support vector machine (SVM)},
+plural={SVMs},
+firstplural={support vector machines (SVMs)}}
\end{verbatim}
+(The value of \ics{acronymtype} varies depending on whether
+the \pkgopt{acronym} package option is used or not.
+The optional argument \meta{key-val list} can be used to
+override any of the \ics{newglossaryentry} keys; for
+example, if the acronym has an irregular plural.)
-\end{enumerate}\ifmakedtx{}{\toTop}
+You can reset an acronym with \ics{glsreset}\marg{label} so that the
+next occurrence displays the long form with the acronym in brackets
+as though it hadn't been used. To do this for all defined
+terms, use \ics{glsresetall}. See
+\ifmakedtx{\autoref{sec:glsunset}}{\htmlref{Unsetting and Resetting Entry Flags}{sec:glsunset}}
+for further details.
+\ifmakedtx{}{\toTop}
\section{Overview of User Commands}\label{sec:overview}
\changes{1.02}{2007 May 25}{added overview section}
@@ -3042,6 +3072,7 @@ the glossary} in the document \url{glossaries.pdf}}.
\ifmakedtx{}{\toTop}
\subsection{Displaying a glossary}
+\label{sec:printglossary}
\DescribeMacro{\printglossaries}
The command \cs{printglossaries} will display all the
@@ -3410,6 +3441,7 @@ Note that \cs{GlsSetXdyFirstLetterAfterDigits} has no effect if
\ifmakedtx{}{\toTop}
\subsection{Defining New Glossaries}
+\label{sec:newglossary}
\DescribeMacro{\newglossary}
A new glossary can be defined using:\\[10pt]