-mglossaries v1.13 (2008/05/18)

git-svn-id: svn://tug.org/texlive/trunk@8285 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 461 insertions, 139 deletions

diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
index c46dc8497f7..d46e6e58645 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
@@ -23,12 +23,14 @@
 \makeatother
 \RecordChanges
 \PageIndex
-\CheckSum{4630}
+\CheckSum{5110}
 \CodelineNumbered
 \newcommand*{\termdef}[1]{\emph{#1}\iterm{#1}}
 \newcommand*{\term}[1]{#1\iterm{#1}}
 \newcommand*{\iterm}[1]{\index{#1|main}}
 \newcommand{\dq}[1]{``#1''}
+\newcommand*{\tableref}[1]{\hyperref[#1]{table~\ref*{#1}}}
+\newcommand*{\Tableref}[1]{\hyperref[#1]{Table~\ref*{#1}}}
 }
 {
 \usepackage{html}
@@ -39,6 +41,8 @@
 \newcommand*{\term}[1]{#1\index{#1}}
 \newcommand*{\iterm}[1]{\index{#1}}
 \newcommand{\dq}[1]{"#1"}
+\newcommand*{\tableref}[1]{\htmlref{table~}{#1}\ref{#1}}
+\newcommand*{\Tableref}[1]{\htmlref{Table~}{#1}\ref{#1}}
 }
 
 
@@ -92,7 +96,7 @@
 \MakeShortVerb{"}
 \DeleteShortVerb{\|}
 
- \title{glossaries.sty v 1.12: \LaTeXe\ Package to Assist Generating Glossaries}
+ \title{glossaries.sty v 1.13: \LaTeXe\ Package to Assist Generating Glossaries}
  \author{Nicola L.C. Talbot\\[10pt]
 School of Computing Sciences\\
 University of East Anglia\\
@@ -100,7 +104,7 @@ Norwich. Norfolk\\
 NR4 7TJ. United Kingdom.\\
 \url{http://theoval.cmp.uea.ac.uk/~nlct/}}
 
- \date{8th March 2008}
+ \date{12th May 2008}
  \maketitle
 \tableofcontents
 
@@ -117,19 +121,6 @@ where only those terms used in the text are added to the glossary.
 This package replaces the \isty{glossary} package which is now
 obsolete.
 
-As from version 1.08, the \sty{glossaries} package now has
-limited multi-lingual support, thanks to all the people who have sent
-me the relevant translations either via email or via comp.text.tex.
-However you must load \isty{babel} \emph{before} 
-\sty{glossaries} to enable this. \ifmakedtx{(See \autoref{sec:predefinednames} for the 
-predefined names used by the \sty{glossaries} package.)}{}
-As from version 1.1, the \sty{glossaries} package also supports 
-Till~Tantau's \isty{translator} package provided it is loaded
-before the \sty{glossaries} package. This makes it easier to change
-the default translations or add new dictionaries.
-If you don't want to use the predefined translations, you can use the
-package option \pkgopt[false]{translate} and supply your own translations.
-
 This documentation is structured as follows: \ifmakedtx{\autoref{sec:quick}}{\htmlref{{A Quick Guide For The Impatient}}{sec:quick}} is for 
 people who want a few quick pointers of how to get started,
 without having to read through lengthy descriptions, 
@@ -139,10 +130,97 @@ and their syntax\ifmakedtx{, \autoref{sec:mfirstuc}}{ and
 \sty{mfirstuc} 
 package\ifmakedtx{, \autoref{sec:code} contains the documented 
 source code for those who want to know more about how the
-package works and how to do more complicated things, such as
-changing the way glossary entries appear}{}.
+package works and \autoref{sec:code:mfirstuc} contains the documented
+code for the \sty{mfirstuc} package}{}.
 \ifmakedtx{}{\toTop}
 
+\subsection{Multi-Lingual Support}
+
+As from version 1.08, the \sty{glossaries} package now has
+limited multi-lingual support, thanks to all the people who have sent
+me the relevant translations either via email or via 
+\texttt{comp.text.tex}.
+However you must load \isty{babel} \emph{before} 
+\sty{glossaries} to enable this. Note that if \isty{babel} is loaded 
+and the \isty{translator} package is detected on \TeX's path, then the
+\isty{translator} package will be loaded automatically.
+
+If you want to use \isty{ngerman} or \isty{german} instead
+of \isty{babel}, you will need to include the \isty{translator} package 
+to provide the translations. For example:
+\begin{verbatim}
+\documentclass[ngerman]{article}
+\usepackage{ngerman}
+\usepackage{translator}
+\usepackage{glossaries}
+\end{verbatim}
+
+The following languages are currently supported:
+\begin{center}
+\begin{tabular}{lc}
+\bfseries Language & \bfseries As from version\\
+Danish & 1.08\\
+Dutch & 1.08\\
+English & 1.08\\
+French & 1.08\\
+German & 1.08\\
+Irish & 1.08\\
+Italian & 1.08\\
+Hungarian & 1.08\\
+Polish & 1.13\\
+Spanish & 1.08
+\end{tabular}
+\end{center}
+The language dependent commands and \isty{translator} keys used by the 
+glossaries package are listed in \tableref{tab:predefinednames}.
+
+\begin{table}[htbp]
+\caption{Customised Text}
+\label{tab:predefinednames}
+\begin{center}
+\begin{tabular}{@{}llp{0.4\linewidth}@{}}
+\bfseries Command Name & \bfseries Translator key word &
+\bfseries What it's for\\
+\ics{glossaryname} & \texttt{Glossary} & Title of the main glossary.\\
+\ics{acronymname} & \texttt{Acronyms} & Title of the list of acronyms
+(when used with package option \pkgopt{acronym}).\\
+\ics{entryname} & \texttt{Notation (glossaries)} & 
+Header for first column in glossary (for 2, 3 or 4 column glossaries 
+that support headers).\\
+\ics{descriptionname} & \texttt{Description (glossaries)} &
+Header for second column in glossary (for 2, 3 or 4 column glossaries
+that support headers).\\
+\ics{symbolname} & \texttt{Symbol (glossaries)} & Header for symbol
+column in glossary for glossary styles that support this option.\\
+\ics{pagelistname} & \texttt{Page List (glossaries)} & 
+Header for page list column in glossary for glossaries that support 
+this option.\\
+\ics{glssymbolsgroupname} & \texttt{Symbols (glossaries)} & 
+Header for symbols section of the glossary for glossary styles that 
+support this option.\\
+\ics{glsnumbersgroupname} & \texttt{Numbers (glossaries)} & Header for
+numbers section of the glossary for glossary styles that support
+this option.
+\end{tabular}
+\end{center}
+\end{table}
+
+Due to the varied nature of glossaries, it's likely that the
+predefined translations may not be appropriate. If you are using
+the \isty{babel} package and do not have the \isty{translator} package
+installed, you need to be familiar with the 
+\ifmakedtx{ advice given in 
+\url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}}{advice on \htmladdnormallink{changing the words babel uses}{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}}. 
+
+If you have the \isty{translator} package installed, then it becomes
+much easier to change the default translations. For example, if you
+are writing in Irish and you want \cs{symbolname} to produce
+\dq{Siombail} instead of \dq{Comhartha}, then you can put the following
+in your document preamble:
+\begin{verbatim}
+\deftranslation[to=Irish]{Symbol (glossaries)}{Siombail}
+\end{verbatim}
+
 \subsection{Generating the associated glossary files}
 \label{sec:makeglossaries}
 
@@ -165,7 +243,8 @@ Perl:
 perl makeglossaries myfile
 \end{verbatim}
 There is a batch file called \texttt{makeglossaries.bat} which
-does this for Windows users.
+does this for Windows users, but you must have Perl installed to
+be able to use it.
 
 If you don't have Perl installed, you will have to run 
 \appname{makeindex} for each glossary type you have defined.
@@ -188,7 +267,7 @@ If any problems occur, remember to check the transcript files
 
 \subsection{Troubleshooting}
 
-The glossaries package comes with a minimal file called 
+The \sty{glossaries} package comes with a minimal file called 
 \texttt{minimalgls.tex} which can be used for testing. This
 should be located in \texttt{texmf/doc/latex/glossaries/samples/}. Further
 information on debugging \LaTeX\ code is available at
@@ -202,8 +281,9 @@ There is a list of frequently asked questions for the
 \label{sec:quick}
 
 This section is for people who want a few quick pointers
-of how to get started, without having to read through
-lengthy descriptions.
+of how to get started. However it is recommended that you read 
+\ifmakedtx{\autoref{sec:overview}}{\htmlref{the overview section}{sec:overview}} 
+for additional commands and advice not listed here.
 
 \begin{enumerate}
 \item Load \sty{glossaries} \emph{after} \isty{hyperref}:
@@ -705,14 +785,6 @@ Since the value of the \gloskey{text} key is obtained from the
 \gloskey{name} key, you will still need to protect fragile commands
 in the \gloskey{name} key if you don't use the \gloskey{text} key. 
 
-\item[\pkgopt{babel}] This is a boolean key and is for use when
-the \sty{glossaries} package is used in conjunction with the
-\isty{babel} package. The default is \pkgopt[true]{babel}, which
-adds the glossary translations to \isty{babel}'s captions. If
-you don't like the translations provided by the \sty{glossaries}
-package, you can set \pkgopt[false]{babel} and provide your own
-translations.
-
 \item[\pkgopt{description}] This option changes the definition of
 \ics{newacronym} to allow a description. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} 
 for further details.
@@ -725,18 +797,31 @@ for further details.
 \ics{newacronym} and the way that acronyms are displayed. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} 
 for further details.
 
+\item[\pkgopt{smaller}] This option changes the definition of
+\ics{newacronym} and the way that acronyms are displayed. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} 
+for further details.
+
 \item[\pkgopt{dua}] This option changes the definition of
 \ics{newacronym} so that acronyms are always expanded. 
 See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} 
 for further details.
 
+\item[\pkgopt{shortcuts}] This option provides shortcut commands
+for acronyms.
+See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} 
+for further details.
+
 \end{description}\ifmakedtx{}{\toTop}
 
 \subsection{Defining Glossary Entries}
 \label{sec:newglosentry}
 
-All glossary entries that are used in a document must be defined in
-the preamble. Only those entries that occur in the document
+All glossary entries must be defined before they are used, so it
+is better to define them in the preamble to ensure this.\footnote{The
+only preamble restriction on \cs{newglossaryentry} and \cs{newacronym}
+was removed in version 1.13, but the restriction remains for
+\cs{loadglsentries}.} However
+only those entries that occur in the document
 (using any of the commands described in \ifmakedtx{\autoref{sec:glslink}}{\htmlref{Links to Glossary Entries}{sec:glslink}} and 
 \ifmakedtx{\autoref{sec:glsadd}}{\htmlref{Adding an entry to the glossary without generating text}{sec:glsadd}}) will appear in the glossary. Each time an entry 
 is used in this way, a line is added to an associated glossary
@@ -795,14 +880,20 @@ key is used.
 
 \item[{\gloskey{plural}}] How the entry will appear in the document text
 when using \ics{glspl} (or one of its uppercase variants).
-If this field is omitted, the value is obtained by appending an
-\dq{s} to the value of the \gloskey{text} field.
-
-\item[{\gloskey{firstplural}}] How the entry will appear in the document
-text the first time it is used with \ics{glspl} (or one of
-its uppercase variants). If this field is omitted, the value is
-obtained by appending an \dq{s} to the value of the \gloskey{first}
-field.
+If this field is omitted, the value is obtained by appending 
+\ics{glspluralsuffix} to the value of the \gloskey{text} field.
+
+\item[{\gloskey{firstplural}}] How the entry will appear in the
+document text the first time it is used with \ics{glspl} (or one of its
+uppercase 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.
+\textbf{Note:} prior to version 1.13, the default value of 
+\gloskey{firstplural} was always taken by appending \dq{s} to the
+\gloskey{first} key, which meant that you had to specify both
+\gloskey{plural} and \gloskey{firstplural}, even if you hadn't
+used the \gloskey{first} key.
 
 \item[{\gloskey{symbol}}] This field is provided to allow the user to
 specify an associated symbol, but most glossary styles ignore
@@ -821,15 +912,15 @@ at-sign @ although the \sty{glossaries} package uses a different
 symbol).
 
 \item[{\gloskey{type}}] This is the glossary type to which this entry
-belongs. If omitted, the default glossary is assumed
-(\texttt{type=main}). The list of acronyms type is given by
+belongs. If omitted, the default glossary is assumed.
+The list of acronyms type is given by
 \ics{acronymtype} which will either be \texttt{main} or
 \texttt{acronym}, depending on whether the \pkgopt{acronym} package
 option was used.
 \end{description}
 Note that if the key starts with an accented letter,
 you must group the accented letter, otherwise it will cause a
-problem for \cs{Gls} and \cs{Glspl}. For example:
+problem for commands like \cs{Gls} and \cs{Glspl}. For example:
 \begin{verbatim}
 \newglossaryentry{elite}{name={{\'e}lite},
 description={select group or class}}
@@ -851,8 +942,55 @@ but don't do \verb|\oe{}sophagus| as it will confuse
 \ics{makefirstuc} (described 
 \ifmakedtx{in \autoref{sec:mfirstuc}}{\htmlref{later}{sec:mfirstuc}}) 
 and will produce \ifmakedtx{\oe{}}{oe}Sophagus instead of 
-\ifmakedtx{{\OE}}{OE}sophagus. 
+\ifmakedtx{{\OE}}{OE}sophagus.
+\ifmakedtx{}{\toTop}
+
+
+\subsubsection{Plurals}
+You may have noticed from above that you can specify the plural form
+when you define a term. If you omit this, the plural will be obtained 
+\DescribeMacro{\glspluralsuffix}by appending \cs{glspluralsuffix} to 
+the singular form. This command defaults to \texttt{s}. For example:
+\begin{verbatim}
+\newglossaryentry{cow}{name=cow,description={a fully grown
+female of any bovine animal}}
+\end{verbatim}
+defines a new entry whose singular form is \dq{cow} and plural form 
+is \dq{cows}. However, if you are writing in archaic English, you 
+may want to use \dq{kine} as the plural form, in which case you would 
+have to do:
+\begin{verbatim}
+\newglossaryentry{cow}{name=cow,plural=kine,
+description={a fully grown female of any bovine animal}}
+\end{verbatim}
+
+If you are writing in a language that supports
+multiple plurals (for a given term) then use the \gloskey{plural} key
+for one of them (typically the one you are most likely to use) and
+for the others you will need to explicitly write the plural form using
+\cs{glslink} rather than using \cs{glspl}. Returning to the cow 
+example above, suppose you will mostly be using \dq{cows} as the
+plural, but occasionally you want to use \dq{kine} as the plural,
+then define the term as
+\begin{verbatim}
+\newglossaryentry{cow}{name=cow,description={a fully grown
+female of any bovine animal (plural cows, archaic plural kine)}}
+\end{verbatim}
+and use \verb|\glspl{cow}| to produce \dq{cows} and use
+\verb|\glslink{cow}{kine}| to produce \dq{kine}.
 
+If you are using a language that usually forms plurals
+by appending a different letter, or sequence of letters, you can
+redefine \cs{glspluralsuffix} as required. However, this must be
+done \emph{before} the entries are defined. For languages that don't
+form plurals by simply appending a suffix, all the plural forms must be 
+specified using the \gloskey{plural} key (and the \gloskey{firstplural}
+key where necessary). 
+
+\ifmakedtx{}{\toTop}
+
+\subsubsection{Loading Entries From a File}
+\label{sec:loadglsentries}
 
 \DescribeMacro{\loadglsentries}
 You can store all your glossary entry definitions in another
@@ -862,8 +1000,64 @@ where \meta{filename} is the name of the file containing all the
 \cs{newglossaryentry} commands. The optional argument
 \meta{type} is the name of the glossary to which those entries
 should belong, for those entries where the \gloskey{type} key has 
-been omitted. Note that only those entries that have been used
-in the text will appear in the relevant glossaries.\ifmakedtx{}{\toTop}
+been omitted (or, more specifically, for those entries whose
+type has been specified by \cs{glsdefaulttype}, which is what
+\cs{newglossaryentry} uses by default). For example, suppose I have
+a file called \texttt{myentries.tex} which contains:
+\begin{verbatim}
+\newglossaryentry{perl}{type=main,
+name={Perl},
+description={A scripting language}}
+
+\newglossaryentry{tex}{name={\TeX},
+description={A typesetting language}}
+
+\newglossaryentry{html}{type=\glsdefaulttype,
+name={html},
+description={A mark up language}}
+\end{verbatim}
+and suppose in my document preamble I use the command:
+\begin{verbatim}
+\loadglsentries[languages]{myentries}
+\end{verbatim}
+then this will add the entries \texttt{tex} and \texttt{html}
+to the glossary whose type is given by \texttt{languages}, but
+the entry \texttt{perl} will be added to the main glossary, since
+it explicitly sets the type to \texttt{main}.
+
+\textbf{Note:} if you
+use \cs{newacronym} (see \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}}) 
+the type is set as \verb|type=\acronymtype| 
+unless you explicitly override it. For example, if my file
+\texttt{myacronyms.tex} contains:
+\begin{verbatim}
+\newacronym{aca}{aca}{a contrived acronym}
+\end{verbatim}
+then (supposing I have defined a new glossary type called
+\texttt{altacronym})
+\begin{verbatim}
+\loadglsentries[altacronym]{myacronyms}
+\end{verbatim}
+will add \texttt{aca} to the glossary type \texttt{acronym}, if the
+package option \pkgopt{acronym} has been specified, or will add
+\texttt{aca} to the glossary type \texttt{altacronym}, if the
+package option \pkgopt{acronym} is not specified. In this instance,
+it is better to change \texttt{myacronyms.tex} to:
+\begin{verbatim}
+\newacronym[type=\glsdefaulttype]{aca}{aca}{a contrived acronym}
+\end{verbatim}
+and now
+\begin{verbatim}
+\loadglsentries[altacronym]{myacronyms}
+\end{verbatim}
+will add \texttt{aca} to the glossary type \texttt{altacronym},
+regardless of whether or not the package option \pkgopt{acronym} is
+used.
+
+Note that only those entries that have been used
+in the text will appear in the relevant glossaries.
+Note also that \cs{loadglsentries} may only be used in the 
+preamble.\ifmakedtx{}{\toTop}
 
 \subsection{Number lists}
 \label{sec:numberlists}
@@ -897,12 +1091,12 @@ font, do:
 \DescribeMacro{\glslink}
 The command:\\[10pt]
 \cs{glslink}\oarg{options}\marg{label}\marg{text}\\[10pt]
-will place \meta{text} in the document at that point and add
-a line into the associated glossary file for the glossary entry
-given by \meta{label}. If hyperlinks are supported, \meta{text}
-will be a hyperlink to the relevant line in the glossary. The
-optional argument \meta{options} must be a \meta{key}=\meta{value} 
-list which can take any of the following keys:
+will place \cs{glstextformat}\marg{text} in the document at that point
+and add a line into the associated glossary file for the glossary entry
+given by \meta{label}. If hyperlinks are supported, \meta{text} will be
+a hyperlink to the relevant line in the glossary. The optional argument
+\meta{options} must be a \meta{key}=\meta{value} list which can take
+any of the following keys:
 
 \begin{description}
 \item[{\gloskey[glslink]{format}}] This specifies how to format the
@@ -1009,7 +1203,13 @@ The command:\\[10pt]
 is the same as \cs{glslink}, except that the \term{link text}
 is determined from the values of the \gloskey{text} and 
 \gloskey{first} keys supplied when the entry was defined using
-\ics{newglossaryentry}. There are two uppercase variants:\\[10pt]
+\ics{newglossaryentry}. If the entry has been marked as having
+been used, the value of the \gloskey{text} key will be used, otherwise
+the value of the \gloskey{first} key will be used. 
+On completion, \cs{gls} will mark the entry given by \meta{label} as
+used.
+
+There are two uppercase variants:\\[10pt]
 \DescribeMacro{\Gls}
 \cs{Gls}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
 and\\[10pt]
@@ -1020,10 +1220,14 @@ uppercase, respectively.
 
 The final optional argument \meta{insert}, allows you to insert
 some additional text into the link text. By default, this will
-append \meta{insert} at the end of the link text. The first optional
-argument \meta{options} is the same as the optional argument to
-\ics{glslink}. As with \cs{glslink}, these commands also have
-a starred version that disable the hyperlink.
+append \meta{insert} at the end of the link text, but this
+can be changed (see 
+\ifmakedtx{\autoref{sec:glsdisplay}}{\htmlref{later}{sec:glsdisplay}}). 
+
+
+The first optional argument \meta{options} is the same as the optional
+argument to \ics{glslink}. As with \cs{glslink}, these commands also
+have a starred version that disable the hyperlink.
 
 There are also analogous plural forms:\\[10pt]
 \DescribeMacro{\glspl}
@@ -1041,7 +1245,8 @@ a starred version that disable the hyperlink.
 \cs{glstext}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
 is similar to \ics{gls} except that it always uses the value
 of the \gloskey{text} key and does not mark the entry as
-having been used.
+having been used. Unlike \cs{gls}, the inserted text \meta{insert} 
+is always appended to the link text.
 
 There are also analogous commands:\\[10pt]
 \DescribeMacro{\Glstext}
@@ -1053,9 +1258,10 @@ the hyperlink.
 
 \DescribeMacro{\glsfirst}The command:\\[10pt]
 \cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
-is similar to \ics{gls} except that it always uses the value
-of the \gloskey{first} key and does not mark the entry as
-having been used.
+is similar to \ics{glstext} except that it always uses the value
+of the \gloskey{first} key. Again, \meta{insert} is always appended
+to the end of the link text and does not mark the entry as having
+been used.
 
 There are also analogous commands:\\[10pt]
 \DescribeMacro{\Glsfirst}
@@ -1067,9 +1273,10 @@ the hyperlink.
 
 \DescribeMacro{\glsplural}The command:\\[10pt]
 \cs{glsplural}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
-is similar to \ics{gls} except that it always uses the value
-of the \gloskey{plural} key and does not mark the entry as
-having been used.
+is similar to \ics{glstext} except that it always uses the value
+of the \gloskey{plural} key. Again, \meta{insert} is always appended
+to the end of the link text and does not mark the entry as having
+been used.
 
 There are also analogous commands:\\[10pt]
 \DescribeMacro{\Glsplural}
@@ -1081,8 +1288,9 @@ the hyperlink.
 
 \DescribeMacro{\glsfirstplural}The command:\\[10pt]
 \cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
-is similar to \ics{gls} except that it always uses the value
-of the \gloskey{firstplural} key and does not mark the entry as
+is similar to \ics{glstext} except that it always uses the value
+of the \gloskey{firstplural} key. Again, \meta{insert} is always 
+appended to the end of the link text and does not mark the entry as
 having been used.
 
 There are also analogous commands:\\[10pt]
@@ -1095,9 +1303,10 @@ the hyperlink.
 
 \DescribeMacro{\glsname}The command:\\[10pt]
 \cs{glsname}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
-is similar to \ics{gls} except that it always uses the value
-of the \gloskey{name} key and does not mark the entry as
-having been used. Note: if you want to use this command and the
+is similar to \ics{glstext} except that it always uses the value of the
+\gloskey{name} key. Again, \meta{insert} is always appended to the end
+of the link text and does not mark the entry as having
+been used.  Note: if you want to use this command and the
 \gloskey{name} key contains commands, you will have to disable the
 \ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} 
 of the \gloskey{name} key and protect fragile commands.
@@ -1112,9 +1321,10 @@ the hyperlink.
 
 \DescribeMacro{\glssymbol}The command:\\[10pt]
 \cs{glssymbol}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
-is similar to \ics{gls} except that it always uses the value
-of the \gloskey{symbol} key and does not mark the entry as
-having been used. Note: if you want to use this command and the
+is similar to \ics{glstext} except that it always uses the value of the
+\gloskey{symbol} key. Again, \meta{insert} is always appended to the
+end of the link text and does not mark the entry as having
+been used.  Note: if you want to use this command and the
 \gloskey{symbol} key contains commands, you will have to disable the
 \ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} 
 of the \gloskey{symbol} key and protect fragile commands.
@@ -1129,10 +1339,12 @@ the hyperlink.
 
 \DescribeMacro{\glsdesc}The command:\\[10pt]
 \cs{glsdesc}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
-is similar to \ics{gls} except that it always uses the value
-of the \gloskey{description} key and does not mark the entry as
-having been used. Note: if you want to use this command and the
-\gloskey{description} key contains commands, you will have to disable the
+is similar to \ics{glstext} except that it always uses the value
+of the \gloskey{description} key. Again, \meta{insert} is always
+appended to the end of the link text and does not mark the entry as 
+having been used.  Note: if you want to use this
+command and the \gloskey{description} key contains commands, you will
+have to disable the
 \ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} 
 of the \gloskey{description} key and protect fragile commands.
 
@@ -1205,7 +1417,7 @@ to use \DescribeMacro{\defglsdisplay}\cs{defglsdisplay} and
 of redefining \cs{glsdisplay} and \cs{glsdisplayfirst}.
 
 Both \cs{defglsdisplay} and \cs{defglsdisplayfirst} take two arguments:
-the first (which is optional) is the glossary name\footnote{\texttt{main} for the main
+the first (which is optional) is the glossary's label\footnote{\texttt{main} for the main
 (default) glossary, \cs{acronymtype} for the list of acronyms, or the
 name supplied in the first mandatory argument to \cs{newglossary} for
 additional glossaries.} and the second is how the term should be
@@ -1225,7 +1437,7 @@ Now suppose you have defined an entry as follows:
 \newglossaryentry{set}{type=notation,
 name=set,
 description={A collection of objects},
-symbol={$S$},
+symbol={$S$}
 }
 \end{verbatim}
 The first time you reference this entry using \cs{gls} it
@@ -1265,25 +1477,36 @@ This is similar to \ics{glslink}, only it doesn't produce
 any text (so therefore, there is no \gloskey[glslink]{hyper} key
 available in \meta{options} but all the other options that can
 be used with \cs{glslink} can be passed to \cs{glsadd}).
+For example, to add a page range to the glossary number list for the
+entry whose label is given by \texttt{set}:
+\begin{verbatim}
+\glsadd[format=(]{set}
+Lots of text about sets spanning many pages.
+\glsadd[format=)]{set}
+\end{verbatim}
 
 \DescribeMacro{\glsaddall}
 To add all entries that have been defined, use:\\[10pt]
-\cs{glsaddall}\oarg{glossary list}\\[10pt]
-If there are multiple glossaries, you can specify to add only
-those entries which belong to the glossaries listed in
-\meta{glossary list} (which must be a comma separated list of
-glossary names). For example:
+\cs{glsaddall}\oarg{options}\\[10pt]
+The optional argument is the same as for \cs{glsadd}, except
+there is also a key \gloskey[glsaddall]{types} which can be
+used to specify which glossaries to use. This should be a
+comma separated list. For example, if you only want to add
+all the entries belonging to the list of acronyms (specified by
+the glossary type \cs{acronymtype}) and a list of
+notation (specified by the glossary type \texttt{notation}) then you can
+do:
 \begin{verbatim}
-\glsaddall[notation]
+\glsaddall[types={\acronymtype,notation}]
 \end{verbatim}
-will add all the entries that have been defined for the glossary
-labelled \dq{notation}.\ifmakedtx{}{\toTop}
+\ifmakedtx{}{\toTop}
 
 \subsection{Displaying a glossary}
 
 \DescribeMacro{\printglossaries}
 The command \cs{printglossaries} will display all the
-defined glossaries. Note that no glossaries will appear until
+glossaries in the order in which they were defined. 
+Note that no glossaries will appear until
 you have either used the Perl script \appname{makeglossaries}
 or have directly used \appname{makeindex} (as described in 
 \ifmakedtx{\autoref{sec:makeglossaries}}{\htmlref{Generating the Associated Glossary Files}{sec:makeglossaries}}). If the glossary still 
@@ -1293,7 +1516,7 @@ Remember that you also need to use the command \ics{makeglossaries} in
 the preamble to enable the glossaries.
 
 \DescribeMacro{\printglossary}
-An individual glossary is displayed using:\\[10pt]
+An individual glossary can be displayed using:\\[10pt]
 \cs{printglossary}\oarg{options}\\[10pt]
 where \meta{options} is a \meta{key}=\meta{value} list of options. 
 The following keys are available:
@@ -1377,16 +1600,16 @@ medium weight small caps, then you can do:
 \DescribeMacro{\newglossary}
 A new glossary can be defined using:\\[10pt]
 \cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\marg{title}\oarg{counter}\\[10pt]
-where \meta{name} is label to assign to this glossary. The arguments
+where \meta{name} is the label to assign to this glossary. The arguments
 \meta{in-ext} and \meta{out-ext} specify the extensions to give to the
 input and output files for that glossary, \meta{title} is the default
 title for this new glossary and the final optional argument
 \meta{counter} specifies which counter to use for the associated number
-lists\iterm{number list} (see also \ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}.) The 
+lists\iterm{number list} (see also \ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}). The 
 first optional argument specifies the extension for the
 \appname{makeindex} transcript file (this information is only used by
 \appname{makeglossaries} which picks up the information from the
-auxiliary file.)
+auxiliary file).
 
 Note that the main (default) glossary is automatically created as:
 \begin{verbatim}
@@ -1411,18 +1634,19 @@ otherwise it is set to \texttt{main}.\ifmakedtx{}{\toTop}
 As you may have noticed in \ifmakedtx{\autoref{sec:newglosentry}}{\htmlref{Defining Glossary Entries}{sec:newglosentry}}, when you 
 specify a new entry, you can specify alternate text to use when
 the term is first used in the document. This provides a useful
-means to define acronyms. The \sty{glossaries} package defines
-the command:\\[10pt]
+means to define acronyms. For convenience, the \sty{glossaries} package
+defines the command:\\[10pt]
 \cs{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}\\[10pt]
-This is equivalent to:\vskip5pt
+By default, this is equivalent to:\vskip5pt
 \begin{ttfamily}\par\noindent
 \cs{newglossaryentry}\textrm{\marg{label}}\{type=\cs{acronymtype},\\
 name=\textrm{\marg{abbrv}},\\
 description=\textrm{\marg{long}},\\
 text=\textrm{\marg{abbrv}},\\
 first=\{\textrm{\meta{long}} (\textrm{\meta{abbrv}})\},\\
-plural=\{\textrm{\meta{abbrv}}s\},\\
-firstplural=\{\textrm{\meta{long}}s (\textrm{\meta{abbrv}}s)\},\\
+plural=\{\textrm{\meta{abbrv}}\cs{glspluralsuffix}\},\\
+firstplural=\{\textrm{\meta{long}}\cs{glspluralsuffix}\cs{space}
+(\textrm{\meta{abbrv}}\cs{glspluralsuffix})\},\\
 \textrm{\meta{key-val list}}\}\par
 \end{ttfamily}
 \vskip5pt
@@ -1431,6 +1655,14 @@ the name of the glossary in which the acronyms should appear. 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.
+
+(\textbf{Note:} since \cs{newacronym} sets \verb|type=\acronymtype|,
+if you want to load a file containing acronym definitions using
+\cs{loadglsentries}\oarg{type}\marg{filename}, the optional argument 
+\meta{type} will not have an effect unless you explicitly set the
+type as \verb|type=\glsdefaulttype|. See \ifmakedtx{\autoref{sec:loadglsentries}}{\htmlref{earlier}{sec:loadglsentries} for details}.)
+
+
 For example, the following defines the acronym IDN:
 \begin{verbatim}
 \newacronym{idn}{IDN}{identification number}
@@ -1448,33 +1680,45 @@ firstplural={identification numbers (IDNs)}}
 so \verb|\gls{idn}| will produce \dq{identification number (IDN)} on
 first use and \dq{IDN} on subsequent uses.
 
-The \sty{glossaries} package has options that change the
-definition of \ics{newacronym} for common acronym formats. These
-options also change the way the link text is displayed for the
-acronyms.
-
-Table~\ref{tab:acronymsettings} lists the package options and
-how the keys are used to store \meta{long} (the long form) and
-\meta{abbrv} (the short form). Note that the \pkgopt{smallcaps}
-option redefines \ics{acronymfont} so that it sets its argument
-in small captials otherwise \cs{acronymfont} simply displays its
-argument in the surrounding font. Note also that if none of
-the package options \pkgopt{smallcaps}, \pkgopt{description}
-or \pkgopt{footnote} are used, \cs{acronymfont} is not used, so
-changing the definition of \cs{acronymfont} will have no effect
-under such circumstances.
+This section describes acronyms that have been defined using
+\cs{newacronym}. If you prefer to define all your acronyms using
+\cs{newglossaryentry} explicitly, then you should skip this section
+and ignore the package options: \pkgopt{smallcaps}, \pkgopt{smaller},
+\pkgopt{description}, \pkgopt{dua}, \pkgopt{footnote} and
+\pkgopt{shortcuts}, as these options change the
+definition of \ics{newacronym} for common acronym formats
+as well as the way that the link text is displayed (see
+\ifmakedtx{\autoref{sec:glsdisplay}}{\htmlref{earlier}{sec:glsdisplay}}). 
+Likewise you should ignore the new commands described in this section,
+such as \cs{acrshort}, as they vary according to the definition of
+\cs{newacronym}.
+
+
+\Tableref{tab:acronymsettings} lists the package options and how the
+\ics{newglossaryentry} keys are used to store \meta{long} (the long 
+form) and \meta{abbrv} (the short form). Note that the 
+\pkgopt{smallcaps} option redefines \ics{acronymfont} so that it sets
+its argument using \cs{textsc} (so you should use lower case characters
+in \meta{abbrv}) and the \pkgopt{smaller} option redefines
+\cs{acronymfont} to use \cs{smaller}\footnote{\cs{smaller} is defined
+in the \sty{relsize} package.}, otherwise \cs{acronymfont} simply
+displays its argument in the surrounding font. Note also that if none
+of the package options \pkgopt{smallcaps}, \pkgopt{smaller},
+\pkgopt{dua}, \pkgopt{description} or \pkgopt{footnote} are used,
+\cs{acronymfont} is not used, so changing the definition of
+\cs{acronymfont} will have no effect under such circumstances.
 
 \begin{table}[htbp]
-\caption{Package options governing acronyms and how the information
-is stored in the glossary keys}
+\caption{Package options governing \cs{newacronym} and how the 
+information is stored in the keys for \cs{newglossaryentry}}
 \label{tab:acronymsettings}
 \begin{center}
 \begin{tabular}{lllll}
 \bfseries Package Option &
-\gloskey{first} &
-\gloskey{text} &
-\gloskey{description} &
-\gloskey{symbol}\\
+\gloskey{first} key &
+\gloskey{text} key &
+\gloskey{description} key &
+\gloskey{symbol} key\\
 \pkgopt{description},\pkgopt{footnote} &
 \meta{abbrv} &
 \meta{abbrv} &
@@ -1500,6 +1744,11 @@ user supplied &
 \meta{abbrv} &
 \meta{long} &
 \meta{abbrv}\\
+\pkgopt{smaller} &
+\meta{long} &
+\meta{abbrv} &
+\meta{long} &
+\meta{abbrv}\\
 \pkgopt{dua} &
 \meta{long} &
 \meta{long} &
@@ -1535,7 +1784,8 @@ matrix}
 If the first use uses the plural form, \verb|\glspl{dm}| will
 display: diagonal matrices (DMs).
 
-Each of the package options \pkgopt{smallcaps}, \pkgopt{footnote}
+Each of the package options \pkgopt{smallcaps}, \pkgopt{smaller}, 
+\pkgopt{footnote}, \pkgopt{dua}
 and \pkgopt{description} use \ics{defglsdisplay} and 
 \ics{defglsdisplayfirst} (described \ifmakedtx{in 
 \autoref{sec:glsdisplay}}{\htmlref{earlier}{sec:glsdisplay}}) 
@@ -1543,7 +1793,7 @@ to change the way the link text is displayed.
 
 \begin{description}
 \item[\pkgopt{description},\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{} 
-When these two options are used together, the first use displays
+When these two package options are used together, the first use displays
 the entry as:\\[10pt]
 \cs{acronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long} 
 \\[10pt]
@@ -1556,22 +1806,22 @@ variants.
 Note also that when these two package options are used (in the
 given order), the \sty{glossaries} package additionally implements the
 \pkgopt{sanitize} option using 
-\ipkgopt[description]{sanitize}\ipkgopt[symbol]{sanitize}\verb|sanitize={description=false,symbol=false}|, so
+\ipkgopt[description]{sanitize}\ipkgopt[symbol]{sanitize}\verb|sanitize={description=false,symbol=false}|, so 
 remember to protect fragile commands when defining acronyms.
 
 \item[dua]\ifmakedtx{\mbox{}\par}{} 
 The \pkgopt{dua} package option always displays the expanded
-form and so may not be used with \pkgopt{footnote} or 
+form and so may not be used with \pkgopt{footnote}, \pkgopt{smaller} or 
 \pkgopt{smallcaps}. Both first use and subsequent use displays the
 entry in the form:\\[10pt]
 \meta{long}\meta{insert}\\[10pt]
-If the \pkgopt{description} option is also used, the \gloskey{name}
-key is set to the long form, otherwise the \gloskey{name} key is
-set to the short form and the \gloskey{description} key is set to
-the long form.
+If the \pkgopt{description} package option is also used, the 
+\gloskey{name} key is set to the long form, otherwise the
+\gloskey{name} key is set to the short form and the
+\gloskey{description} key is set to the long form.
 
 \item[\pkgopt{description}]\ifmakedtx{\mbox{}\par}{} 
-This option displays the entry on first use as:\\[10pt]
+This package option displays the entry on first use as:\\[10pt]
 \meta{long}\meta{insert} (\cs{acronymfont}\marg{abbrv})\\[10pt]
 while subsequent use displays the entry as:\\[10pt]
 \cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
@@ -1581,7 +1831,7 @@ package additionally implements the option
 remember to protect fragile commands when defining acronyms.
 
 \item[\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{} 
-This option displays the entry on first use as:\\[10pt]
+This package option displays the entry on first use as:\\[10pt]
 \cs{acronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long}\\[10pt]
 while subsequent use displays the entry as:\\[10pt]
 \cs{acronymfont}\marg{abbrv}\meta{insert}
@@ -1597,7 +1847,21 @@ have been set, this option displays the entry on first use as:\\[10pt]
 \meta{long}\meta{insert} (\cs{acronymfont}\marg{abbrv})\\[10pt]
 while subsequent use displays the entry as:\\[10pt]
 \cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
-where \cs{acronymfont} is set to \cs{textsc}.
+where \cs{acronymfont} is set to \verb|\textsc{#1}|, so \meta{abbrv}
+should be specified in lower case.
+
+Note also that if this package option is used, the \sty{glossaries}
+package additionally implements the option 
+\ipkgopt[symbol]{sanitize}\verb|sanitize={symbol=false}|, so
+remember to protect fragile commands when defining acronyms.
+
+\item[\pkgopt{smaller}]\ifmakedtx{\mbox{}\par}{} 
+If neither the \pkgopt{footnote} nor \pkgopt{description} options
+have been set, this option displays the entry on first use as:\\[10pt]
+\meta{long}\meta{insert} (\cs{acronymfont}\marg{abbrv})\\[10pt]
+while subsequent use displays the entry as:\\[10pt]
+\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
+where \cs{acronymfont} is set to \verb|{\smaller #1}|.
 
 Note also that if this package option is used, the \sty{glossaries}
 package additionally implements the option 
@@ -1605,9 +1869,9 @@ package additionally implements the option
 remember to protect fragile commands when defining acronyms.
 
 \item[None of the above]\ifmakedtx{\mbox{}\par}{} 
-If none of the package options \pkgopt{smallcaps}, \pkgopt{footnote}
-or \pkgopt{description} are used, then on first use the entry is
-displayed as:\\[10pt]
+If none of the package options \pkgopt{smallcaps}, \pkgopt{smaller},
+\pkgopt{footnote}, \pkgopt{dua} or \pkgopt{description} are used, 
+then on first use the entry is displayed as:\\[10pt]
 \meta{long} (\meta{abbrv})\meta{insert}\\[10pt]
 while subsequent use displays the entry as:\\[10pt]
 \cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
@@ -1661,16 +1925,49 @@ may additionally need to change the above commands as well as
 the changing way the text is displayed using \ics{defglsdisplay}
 and \ics{defglsdisplayfirst}.
 
+The package option \pkgopt{shortcuts} provides the synonyms listed
+in \tableref{tab:shortcuts}. If any of those commands generate
+an \dq{undefined control sequence} error message, check that you
+have enabled the shortcuts using the \pkgopt{shortcuts} package 
+option. Note that there are no shortcuts for the commands that
+produce all upper case text.
+
+\begin{table}[htbp]
+\caption{Synonyms provided by the package option \pkgopt{shortcuts}}
+\label{tab:shortcuts}
+\begin{center}
+\begin{tabular}{ll}
+\bfseries Shortcut Command & \bfseries Equivalent Command\\
+\ics{acs} & \ics{acrshort}\\
+\ics{Acs} & \ics{Acrshort}\\
+\ics{acsp} & \ics{acrshortpl}\\
+\ics{Acsp} & \ics{Acrshortpl}\\
+\ics{acl} & \ics{acrlong}\\
+\ics{Acl} & \ics{Acrlong}\\
+\ics{aclp} & \ics{acrlongpl}\\
+\ics{Aclp} & \ics{Acrlongpl}\\
+\ics{acf} & \ics{acrfull}\\
+\ics{Acf} & \ics{Acrfull}\\
+\ics{acfp} & \ics{acrfullpl}\\
+\ics{Acfp} & \ics{Acrfullpl}\\
+\ics{ac} & \ics{gls}\\
+\ics{Ac} & \ics{Gls}\\
+\ics{acp} & \ics{glspl}\\
+\ics{Acp} & \ics{Glspl}
+\end{tabular}
+\end{center}
+\end{table}
+
 \ifmakedtx{}{\toTop}
 
 \subsection{Unsetting and resetting entry flags}
 
-When using commands such as \ics{gls} it is possible that you may want
-to use the value given by the \gloskey{first} key, even though you have
-already used the glossary entry. Conversely, you may want to use the
-value given by the \gloskey{text} key, even though you haven't used the
-glossary entry.  The former can be achieved by one of the following
-commands:\\[10pt]
+When using \ics{gls}, \ics{glspl} and their uppercase variants it is
+possible that you may want to use the value given by the
+\gloskey{first} key, even though you have already used the glossary
+entry. Conversely, you may want to use the value given by the
+\gloskey{text} key, even though you haven't used the glossary entry.
+The former can be achieved by one of the following commands:\\[10pt]
 \DescribeMacro{\glsreset}\cs{glsreset}\marg{label}\\
 \DescribeMacro{\glslocalreset}\cs{glslocalreset}\marg{label}\\[10pt]
 while the latter can be achieved by one of the following commands:\\[10pt]
@@ -1694,7 +1991,7 @@ glossary styles. These are as follows:
 environment. The entry name is placed in the optional argument
 of the \cs{item} command (so it will appear in bold by
 default). The description follows, and then the associated number
-list for that entry.
+list for that entry. Sub groups are separated using \cs{indexspace}.
 
 \item[listgroup] The \glostyle{listgroup} style is like 
 \glostyle{list} but the glossary groups have headings.
@@ -1725,6 +2022,7 @@ supplied by Axel~Menzel.}
 environment (defined by the \isty{longtable} package). It has two
 columns: the first column contains the entry's name and the second
 column contains the description followed by the \term{number list}.
+Sub groups are separated with a blank row.
 
 \item[longborder] The \glostyle{longborder} style is like
 \glostyle{long} but has horizontal and vertical lines around it.
@@ -1771,6 +2069,7 @@ around it.
 environment (defined by the \isty{supertabular} package). It has two
 columns: the first column contains the entry's name and the second
 column contains the description followed by the \term{number list}.
+Sub groups are separated with a blank row.
 
 \item[superborder] The \glostyle{superborder} style is like
 \glostyle{super} but has horizontal and vertical lines around it.
@@ -1825,7 +2124,7 @@ All the styles except for the three- and four-column styles and the
 \glostyle{listdotted} style use the command
 \DescribeMacro{\glspostdescription}\cs{glspostdescription} after the
 description. This simply displays a full stop by default.  To eliminate
-this full stop (or replace it with something else, say a comma), you
+this full stop (or replace it with something else, say a comma) you
 will need to redefine \cs{glspostdescription} before the glossary is
 displayed.\ifmakedtx{}{\toTop}
 
@@ -2026,6 +2325,29 @@ than \cs{emph}.)
 Note however that \verb|\makefirstuc{\ae{}bc}| produces \ae Bc since
 the empty group following \cs{ae} is considered to be the argument
 of \cs{ae} which is in fact not the case.
+
+Note also that
+\begin{verbatim}
+\newcommand{\abc}{abc}
+\makefirstuc{\abc}
+\end{verbatim}
+produces: ABC. This is because the first object in the argument of
+\cs{makefirstuc} is \cs{abc}, so it does \verb|\MakeUppercase{\abc}|.
+Whereas:
+\begin{verbatim}
+\newcommand{\abc}{abc}
+\expandafter\makefirstuc\expandafter{\abc}
+\end{verbatim}
+produces: Abc. There is a short cut command which will do this:\\[10pt]
+\DescribeMacro{\xmakefirstuc}
+\cs{xmakefirstuc}\marg{stuff}\\[10pt]
+This is equivalent to \cs{expandafter}\cs{makefirstuc}\cs{expandafter}\marg{stuff}. So
+\begin{verbatim}
+\newcommand{\abc}{abc}
+\xmakefirstuc{\abc}
+\end{verbatim}
+produces: Abc.
+
 \ifmakedtx{}{\toTop}
 
  \StopEventually{\clearpage\phantomsection\addcontentsline{toc}{section}{Index}\PrintIndex}