summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex832
1 files changed, 577 insertions, 255 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
index 55746a63862..1eb073f2961 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
@@ -1,6 +1,7 @@
\documentclass[a4paper]{ltxdoc}
\usepackage{ifthen}
\usepackage{alltt}
+\usepackage{pifont}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[colorlinks,
@@ -25,7 +26,7 @@
\makeatother
\RecordChanges
\PageIndex
-\CheckSum{7758}
+\CheckSum{7872}
\CodelineNumbered
\newcommand*{\termdef}[1]{\emph{#1}\iterm{#1}}
\newcommand*{\term}[1]{#1\iterm{#1}}
@@ -45,6 +46,7 @@
}{\end{minipage}\end{lrbox}%
\par\vskip10pt\noindent
\fcolorbox{red}{white}{\usebox{\importantbox}}\par\vskip10pt}
+\newcommand*{\tick}{\ding{51}}
}
{
\usepackage{html}
@@ -58,10 +60,17 @@
\newcommand*{\tableref}[1]{\htmlref{table~}{#1}\ref{#1}}
\newcommand*{\Tableref}[1]{\htmlref{Table~}{#1}\ref{#1}}
\newenvironment{important}{}{}
+\newcommand*{\tick}{X}
}
+\newcommand*{\ifirstuse}{\iterm{first use}}
+\newcommand*{\firstuse}{first use\ifirstuse}
+\newcommand*{\firstuseflag}{first use flag\ifirstuseflag}
+\newcommand*{\firstusetext}{first use text\ifirstusetext}
\ifmakedtx{
+\newcommand*{\ifirstuseflag}{\iterm{first use>flag}}
+\newcommand*{\ifirstusetext}{\iterm{first use>text}}
\newcommand*{\istkey}[1]{\texttt{#1}\index{makeindex=\texttt{makeindex}>#1=\texttt{#1}|hyperpage}}
\newcommand*{\locfmt}[1]{\texttt{#1}\SpecialMainIndex{#1}}
\newcommand*{\ics}[1]{\texttt{\char`\\#1}\SpecialMainIndex{#1}}
@@ -88,6 +97,8 @@
\newcommand*{\envname}[1]{\textsf{#1}}
}
{
+\newcommand*{\ifirstuseflag}{\iterm{first use!flag}}
+\newcommand*{\ifirstusetext}{\iterm{first use!text}}
\newcommand{\istkey}[1]{\texttt{#1}\index{makeindex key!#1}}
\newcommand{\locfmt}[1]{\texttt{#1}\index{#1@\cs{#1}}}
\newcommand{\ics}[1]{\texttt{\char`\\#1}\index{#1@\cs{#1}}}
@@ -119,7 +130,7 @@
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{glossaries.sty v 1.17: \LaTeXe\ Package to Assist Generating Glossaries}
+ \title{glossaries.sty v 1.18: \LaTeXe\ Package to Assist Generating Glossaries}
\author{Nicola L.C. Talbot\\[10pt]
School of Computing Sciences\\
University of East Anglia\\
@@ -127,7 +138,7 @@ Norwich. Norfolk\\
NR4 7TJ. United Kingdom.\\
\url{http://theoval.cmp.uea.ac.uk/~nlct/}}
- \date{26th December 2008}
+ \date{14th January 2009}
\maketitle
\tableofcontents
@@ -139,8 +150,14 @@ glossaries. It has a certain amount of flexibility, allowing the
user to customize the format of the glossary and define multiple
glossaries. It also supports acronyms and glossary styles that
include symbols (in addition to a name and description) for glossary
-entries. There is provision for loading a database of glossary terms
-where only those terms used in the text are added to the glossary.
+entries. There is provision for loading a database of glossary terms.
+Only those terms used\footnote{that is, if the term has been
+referenced using any of the commands described in \ifmakedtx{\autoref{sec:glslink}}{%
+\htmlref{Links to Glossary Entries}{sec:glslink}},
+\ifmakedtx{\autoref{sec:glsadd}}{\htmlref{Adding an Entry to the
+Glossary Without Generating Text}{sec:glsadd}} or
+via \ics{glssee} (or the \gloskey{see} key)} in the document will be
+added to the glossary.
\textbf{This package replaces the \isty{glossary} package which is
now obsolete. Please see the file
@@ -171,8 +188,8 @@ The Impatient}}{sec:quick}} is for people who want a few quick
pointers of how to get started creating a basic glossary, without
having to read through lengthy descriptions.
-\item \ifmakedtx{\autoref{sec:overview}}{\htmlref{Overview}{sec:overview}}
-gives an overview of available commands and their syntax.
+\item \ifmakedtx{\autoref{sec:overview}}{\htmlref{Overview of User Commands}{sec:overview}}
+gives an overview of the main user commands and their syntax.
\item \ifmakedtx{\autoref{sec:mfirstuc}}{\htmlref{Mfirstuc}{sec:mfirstuc}}
describes the associated \sty{mfirstuc} package.
@@ -217,7 +234,7 @@ according to your operating system and \TeX\ distribution.
The sample documents are as follows:
\begin{description}
-\item[minimalgls.tex] This document is a minimal working example.
+\item[minimalgls.tex]\label{ex:minimalgls} This document is a minimal working example.
You can test your installation using this file. To create the
complete document you will need to do the following steps:
\begin{enumerate}
@@ -232,6 +249,12 @@ latex minimalgls
PDF\LaTeX\ you will also get warnings about non-existent
references. These warnings may be ignored on the first run.
+ If you get a \verb"Missing \begin{document}" error, then
+ it's most likely that your version of \isty{xkeyval} is
+ out of date. Check the log file for a warning of that nature.
+ If this is the case, you will need to update the \sty{xkeyval}
+ package.
+
\item Run \appname{makeglossaries} on the document. This can
be done on a terminal by either typing
\begin{verbatim}
@@ -263,7 +286,7 @@ You should now have a complete document. The number following
each entry in the glossary is the location number. By default, this
is the page number where the entry was referenced.
-\item[sample4col.tex] This document illustrates a four column
+\item[sample4col.tex]\label{ex:sample4col} This document illustrates a four column
glossary where the entries have a symbol in addition to the
name and description. To create the complete document, you need
to do:
@@ -282,9 +305,9 @@ style has been set:
\renewcommand*{\glsgroupskip}{}
\end{verbatim}
-\item[sampleAcr.tex] This document has some sample acronyms. It
+\item[sampleAcr.tex]\label{ex:sampleAcr} This document has some sample acronyms. It
also adds the glossary to the table of contents, so an extra
-run through \LaTeX\ is required to ensure the document is up-to-date:
+run through \LaTeX\ is required to ensure the document is up to date:
\begin{verbatim}
latex sampleAcr
makeglossaries sampleAcr
@@ -292,7 +315,7 @@ latex sampleAcr
latex sampleAcr
\end{verbatim}
-\item[sampleAcrDesc.tex] This is similar to the previous example,
+\item[sampleAcrDesc.tex]\label{ex:sampleAcrDesc} This is similar to the previous example,
except that the acronyms have an associated description. As with
the previous example, the glossary is added to the table of
contents, so an extra run through \LaTeX\ is required:
@@ -303,7 +326,7 @@ latex sampleAcrDesc
latex sampleAcrDesc
\end{verbatim}
-\item[sampleDesc.tex] This is similar to the previous example,
+\item[sampleDesc.tex]\label{ex:sampleDesc} This is similar to the previous example,
except that it defines the acronyms using \ics{newglossaryentry}
instead of \ics{newacronym}. As with
the previous example, the glossary is added to the table of
@@ -315,8 +338,8 @@ latex sampleDesc
latex sampleDesc
\end{verbatim}
-\item[sampleDB.tex] This document illustrates how to load
-an external files containing the glossary definitions. It also
+\item[sampleDB.tex]\label{ex:sampleDB} This document illustrates how to load
+external files containing the glossary definitions. It also
illustrates how to define a new glossary type. This document
has the \term{number list} suppressed and uses \ics{glsaddall} to add
all the entries to the glossaries without referencing each one
@@ -326,10 +349,11 @@ latex sampleDB
makeglossaries sampleDB
latex sampleDB
\end{verbatim}
-The glossary definitions are stored in the files
+The glossary definitions are stored in the accompanying files
\texttt{database1.tex} and \texttt{database2.tex}. Note that if
you don't have Perl installed, you will need to use
-\appname{makeindex} twice instead of using \appname{makeglossaries}:
+\appname{makeindex} twice instead of a single call to
+\appname{makeglossaries}:
\begin{enumerate}
\item Create the main glossary:
\begin{verbatim}
@@ -341,7 +365,7 @@ makeindex -s sampleDB.ist -t sampleDB.nlg -o sampleDB.not sampleDB.ntn
\end{verbatim}
\end{enumerate}
-\item[sampleEq.tex] This document illustrates how to change the
+\item[sampleEq.tex]\label{ex:sampleEq} This document illustrates how to change the
location to something other than the page number. In this case,
the \texttt{equation} counter is used since all glossary entries
appear inside an \envname{equation} environment. To create the
@@ -352,7 +376,7 @@ makeglossaries sampleEq
latex sampleEq
\end{verbatim}
-\item[sampleEqPg.tex] This is similar to the previous example,
+\item[sampleEqPg.tex]\label{ex:sampleEqPg} This is similar to the previous example,
but the number lists\iterm{number list} are a mixture of page
numbers and equation numbers. This example adds the glossary to the
table of contents, so an extra \LaTeX\ run is required:
@@ -363,7 +387,7 @@ latex sampleEqPg
latex sampleEqPg
\end{verbatim}
-\item[sampleSec.tex] This document also illustrates how to change
+\item[sampleSec.tex]\label{ex:sampleSec} This document also illustrates how to change
the location to something other than the page number. In this case,
the \texttt{section} counter is used. This example adds the
glossary to the table of contents, so an extra \LaTeX\ run is
@@ -375,7 +399,7 @@ latex sampleSec
latex sampleSec
\end{verbatim}
-\item[sampleNtn.tex] This document illustrates how to create
+\item[sampleNtn.tex]\label{ex:sampleNtn} This document illustrates how to create
an additional glossary type. This example adds the glossary to the
table of contents, so an extra \LaTeX\ run is required:
\begin{verbatim}
@@ -385,7 +409,8 @@ latex sampleNtn
latex sampleNtn
\end{verbatim}
Note that if you don't have Perl installed, you will need to use
-\appname{makeindex} twice instead of using \appname{makeglossaries}:
+\appname{makeindex} twice instead of a single call to
+\appname{makeglossaries}:
\begin{enumerate}
\item Create the main glossary:
\begin{verbatim}
@@ -397,7 +422,7 @@ makeindex -s sampleNtn.ist -t sampleNtn.nlg -o sampleNtn.not sampleNtn.ntn
\end{verbatim}
\end{enumerate}
-\item[sample.tex] This document illustrates some of the basics,
+\item[sample.tex]\label{ex:sample} This document illustrates some of the basics,
including how to create child entries that use the same name as the
parent entry. This example adds the glossary to the table of
contents, so an extra \LaTeX\ run is required:
@@ -414,7 +439,7 @@ effect if you use \appname{makeglossaries}. If you use
\appname{makeindex} explicitly, you will need to use the
\texttt{-l} switch to indicate letter ordering.)
-\item[sampletree.tex] This document illustrates a hierarchical
+\item[sampletree.tex]\label{ex:sampletree} This document illustrates a hierarchical
glossary structure where child entries have different names
to their corresponding parent entry. To create the document do:
\begin{verbatim}
@@ -423,7 +448,7 @@ makeglossaries sampletree
latex sampletree
\end{verbatim}
-\item[samplexdy.tex] This document illustrates how to use the
+\item[samplexdy.tex]\label{ex:samplexdy} This document illustrates how to use the
\sty{glossaries} package with \appname{xindy} instead of
\appname{makeindex}. The document uses UTF8 encoding (with the
\isty{inputenc} package). The encoding is picked up by
@@ -466,7 +491,7 @@ xindy -I xindy -M samplexdy-mc -t samplexdy.glg -o samplexdy.gls
samplexdy.glo
\end{verbatim}
-\item[sampleutf8.tex] This is another example that uses
+\item[sampleutf8.tex]\label{ex:sampleutf8} This is another example that uses
\appname{xindy}. Unlike \appname{makeindex}, \appname{xindy} can
cope with accented or non-Latin characters. This document uses
UTF8 encoding. To create the document do:
@@ -483,7 +508,8 @@ xindy -L english -C utf8 -I xindy -M sampleutf8 -t sampleutf8.glg
-o sampleutf8.gls sampleutf8.glo
\end{verbatim}
-If you remove the \pkgopt{xindy} option and do:
+If you remove the \pkgopt{xindy} option from \texttt{sampleutf8.tex}
+and do:
\begin{verbatim}
latex sampleutf8
makeglossaries sampleutf8
@@ -602,8 +628,8 @@ glossaries package are listed in \tableref{tab:predefinednames}.
\label{tab:predefinednames}
\begin{center}
\begin{tabular}{@{}llp{0.4\linewidth}@{}}
-\bfseries Command Name & \bfseries Translator key word &
-\bfseries What it's for\\
+\bfseries Command Name & \bfseries Translator Key Word &
+\bfseries Purpose\\
\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}).\\
@@ -692,7 +718,7 @@ explicitly}{sec:xindyapp}}), otherwise you will need to use
explicitly}{sec:makeindexapp}}). Note that some commands and
package options have no effect if you don't use
\appname{makeglossaries}. These are listed in
-Table~\ref{tab:makeglossariesCmds}.
+\tableref{tab:makeglossariesCmds}.
Note that if any of your entries use an entry
that is not referenced outside the glossary, you will need to
@@ -805,7 +831,8 @@ files, you must make sure you have used the
\usepackage[xindy]{glossaries}
\end{verbatim}
This is required regardless of whether you use \appname{xindy}
-explicitly or via \appname{makeglossaries}. This causes the glossary
+explicitly or whether it's called implicitly via
+\appname{makeglossaries}. This causes the glossary
entries to be written in raw \appname{xindy} format, so you need to
use \texttt{-I xindy} \emph{not} \texttt{-I tex}.
@@ -817,14 +844,15 @@ xindy -L \textrm{\meta{language}} -C \textrm{\meta{encoding}} -I xindy
-o \textrm{\meta{base}}.gls \textrm{\meta{base}}.glo
\end{ttfamily}
\\[10pt]
-where \meta{language} is required language name, \meta{encoding} is
-the encoding, \meta{base} is the name of the document without
-the \filetype{.tex} extension and \meta{style} is the name of the
-\appname{xindy} style file without the \filetype{.xdy} extension. The
-default name for this style file is \meta{base}\filetype{.xdy} but
-can be changed via \ics{setStyleFile}\marg{style}. You may need to
-specify the full path name. If any of the file names contain spaces,
-you must delimit them using double-quotes.
+where \meta{language} is the required language name, \meta{encoding}
+is the encoding, \meta{base} is the name of the document without the
+\filetype{.tex} extension and \meta{style} is the name of the
+\appname{xindy} style file without the \filetype{.xdy} extension.
+The default name for this style file is \meta{base}\filetype{.xdy}
+but can be changed via \ics{setStyleFile}\marg{style}. You may need
+to specify the full path name depending on the current working
+directory. If any of the file names contain spaces, you must delimit
+them using double-quotes.
For example, if your document is called \texttt{myDoc.tex} and
you are using UTF8 encoding in English, then type the
@@ -855,7 +883,7 @@ makeglossaries myDoc
Note also that some commands and package options have no effect if
you use \appname{xindy} explicitly instead of using
\appname{makeglossaries}. These are listed in
-Table~\ref{tab:makeglossariesCmds}.
+\tableref{tab:makeglossariesCmds}.
\ifmakedtx{}{\toTop}
\subsubsection{Using makeindex explicitly}
@@ -906,7 +934,7 @@ makeglossaries myDoc
Note also that some commands and package options have no effect if
you use \appname{makeindex} explicitly instead of using
\appname{makeglossaries}. These are listed in
-Table~\ref{tab:makeglossariesCmds}.
+\tableref{tab:makeglossariesCmds}.
\ifmakedtx{}{\toTop}
\subsection{Troubleshooting}
@@ -927,17 +955,25 @@ other queries, consult the \sty{glossaries} FAQ at
\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/packages/faq/glossariesfaq.html}.
\begin{enumerate}
-\item I've used the \pkgopt{smallcaps} option, but the acronyms
+\item \textbf{Q.} I get the error message:
+\begin{verbatim}
+Missing \begin{document}
+\end{verbatim}
+
+\textbf{A.} Check you are using an up to date version of the \isty{xkeyval}
+package.
+
+\item \textbf{Q.} I've used the \pkgopt{smallcaps} option, but the acronyms
are displayed in normal sized upper case letters.
-The \pkgopt{smallcaps} package option uses \cs{textsc} to typeset
+\textbf{A.} The \pkgopt{smallcaps} package option uses \cs{textsc} to typeset
the acronyms. This command converts lower case letters to small
capitals, while upper case letters remain their usual size. Therefore
you need to specify the acronym in lower case letters.
-\item How do I change the font that the acronyms are displayed in?
+\item \textbf{Q.} How do I change the font that the acronyms are displayed in?
-The easiest way to do this is to specify the \pkgopt{smaller} package
+\textbf{A.} The easiest way to do this is to specify the \pkgopt{smaller} package
option and redefine \cs{acronymfont} to use the required typesetting
command. For example, suppose you would like the acronyms displayed in
a sans-serif font, then you can do:
@@ -946,44 +982,47 @@ a sans-serif font, then you can do:
\renewcommand*{\acronymfont}[1]{\textsf{#1}}
\end{verbatim}
-\item How do I change the font that the acronyms are displayed in
-on first use?
+\item \textbf{Q.} How do I change the font that the acronyms are displayed in
+on \firstuse?
-The easiest way to do this is to specify the \pkgopt{smaller} package
+\textbf{A.} The easiest way to do this is to specify the \pkgopt{smaller} package
option and redefine \cs{firstacronymfont} to use the required
command. Note that if you don't want the acronym on subsequent use
to use \cs{smaller}, you will also need to redefine \cs{acronymfont},
-as above. For example to make the acronym emphasized on first use,
-but use the surrounding font for subsequent use, you can do:
+as above. For example to make the acronym emphasized on
+\firstuse, but use the surrounding font for subsequent use, you can do:
\begin{verbatim}
\usepackage[smaller]{glossaries}
\renewcommand*{\firstacronymfont}[1]{\emph{#1}}
\renewcommand*{\acronymfont}[1]{#1}
\end{verbatim}
-\item I don't have Perl installed, do I have to use
+\item \textbf{Q.} I don't have Perl installed, do I have to use
\appname{makeglossaries}?
-Read \ifmakedtx{\autoref{sec:xindyapp}}{\htmlref{Using
+\textbf{A.} Although it is strongly recommended that you use
+\appname{makeglossaries}, you don't have to use it.
+For further details, read
+\ifmakedtx{\autoref{sec:xindyapp}}{\htmlref{Using
xindy explicitly}{sec:xindyapp}} or
\ifmakedtx{\autoref{sec:makeindexapp}}{\htmlref{Using
makeindex explicitly}{sec:makeindexapp}}, depending on
whether you want to use \appname{xindy} or \appname{makeindex}.
-\item I'm used to using the \sty{glossary} package: are there any
+\item \textbf{Q.} I'm used to using the \sty{glossary} package: are there any
instructions on migrating from the \isty{glossary} package to the
\sty{glossaries} package?
-Read \ifmakedtx{the file \texttt{glossary2glossaries.pdf}}{\htmladdnormallink{Upgrading
+\textbf{A.} Read \ifmakedtx{the file \texttt{glossary2glossaries.pdf}}{\htmladdnormallink{Upgrading
from the glossary package to the glossaries
package}{glossary2glossaries.html}} which should be available from the
same location as this document.
-\item I'm using \isty{babel} but the fixed names haven't been
+\item \textbf{Q.} I'm using \isty{babel} but the fixed names haven't been
translated.
-The \sty{glossaries} package currently only supports the following
+\textbf{A.} The \sty{glossaries} package currently only supports the following
languages: Brazilian Portuguese, Danish, Dutch, English, French,
German, Irish, Italian, Hungarian, Polish and Spanish. If you want
to add another language, send me the translations, and I'll add them
@@ -1002,9 +1041,9 @@ Alternatively, you can add the language as a global option
to the class file. Check the \sty{translator} package documentation
for further details.
-\item My glossaries haven't appeared.
+\item \textbf{Q.} My glossaries haven't appeared.
-Remember to do the following:
+\textbf{A.} Remember to do the following:
\begin{itemize}
\item Add \ics{makeglossaries} to the document preamble.
@@ -1016,8 +1055,8 @@ been defined or \ics{printglossaries}.
Entries}{sec:glslink}},
\ifmakedtx{\autoref{sec:glsadd}}{\htmlref{Adding an Entry to the
Glossary Without Generating Text}{sec:glsadd}} or
-\ifmakedtx{\autoref{sec:glssee}}{\htmlref{Cross-Referencing
-Entries}{sec:glssee}} for each entry
+\ifmakedtx{\autoref{sec:crossref}}{\htmlref{Cross-Referencing
+Entries}{sec:crossref}} for each entry
that you want to appear in the glossary.
\item Run \LaTeX\ on your document, then run \appname{makeglossaries},
@@ -1331,7 +1370,7 @@ plural=matrices}
In this example, the entry name appears as \dq{Matrix} in the
glossary, and either \dq{matrix} or \dq{matrices} in the text.
-\item The way the term appears on first use can be different
+\item The way the term appears on \firstuse\ can be different
to the way it appears subsequently:
\begin{verbatim}
\newglossaryentry{singmtx}{name=Singular Matrix,
@@ -1546,7 +1585,7 @@ appear in unnumbered subsections:
\end{enumerate}\ifmakedtx{}{\toTop}
-\section{Overview}\label{sec:overview}
+\section{Overview of User Commands}\label{sec:overview}
\changes{1.02}{2007 May 25}{added overview section}
\subsection{Package Options}
@@ -1566,7 +1605,7 @@ used without \pkgopt{numberline}, the title will be aligned with
the section numbers rather than the section titles.
\item[\pkgopt{acronym}] This creates a new glossary with the
-label \texttt{acronym}:
+label \texttt{acronym}. This is equivalent to:
\begin{verbatim}
\newglossary[alg]{acronym}{acr}{acn}{\acronymname}
\end{verbatim}
@@ -1575,9 +1614,10 @@ is set to \texttt{acronym} otherwise it is set to
\texttt{main}.\footnote{Actually it sets \ics{acronymtype} to
\ics{glsdefaulttype} if the \pkgopt{acronym} package option is
not used, but \ics{glsdefaulttype} usually has the value
-\texttt{main}.}
+\texttt{main}.}
Entries that are defined using \ics{newacronym} are placed in
-the glossary whose label is given by \ics{acronymtype}.
+the glossary whose label is given by \ics{acronymtype}, unless
+another glossary is explicitly specified.
\item[\pkgopt{section}] This is a \meta{key}=\meta{value} option. Its
value should be the name of a sectional unit (e.g.\ chapter).
@@ -1655,6 +1695,44 @@ The list of acronyms is in section~\ref{\glsautoprefix\acronymtype}.
value should be the name of the glossary style to use. Predefined
glossary styles are listed \ifmakedtx{in \autoref{sec:styles}}{\htmlref{later}{sec:styles}}.
+\item[\pkgopt{nolong}] This prevents the \sty{glossaries} package
+from automatically loading \isty{glossary-long} (which means that
+the \isty{longtable} package also won't be loaded). This reduces
+overhead by not defining unwanted styles and commands. Not that if
+you use this option, you won't be able to use any of the
+glossary styles defined in the \sty{glossary-long} package.
+
+\item[\pkgopt{nosuper}] This prevents the \sty{glossaries} package
+from automatically loading \isty{glossary-super} (which means that
+the \isty{supertabular} package also won't be loaded). This reduces
+overhead by not defining unwanted styles and commands. Not that if
+you use this option, you won't be able to use any of the
+glossary styles defined in the \sty{glossary-super} package.
+
+\item[\pkgopt{nolist}] This prevents the \sty{glossaries} package
+from automatically loading \isty{glossary-list}. This reduces
+overhead by not defining unwanted styles. Not that if
+you use this option, you won't be able to use any of the
+glossary styles defined in the \sty{glossary-list} package.
+Note that since the default style is \glostyle{list}, you will
+also need to use the \pkgopt{style} option to set the style to
+something else.
+
+\item[\pkgopt{notree}] This prevents the \sty{glossaries} package
+from automatically loading \isty{glossary-tree}. This reduces
+overhead by not defining unwanted styles. Not that if
+you use this option, you won't be able to use any of the
+glossary styles defined in the \sty{glossary-tree} package.
+
+\item[\pkgopt{nostyles}] This prevents all the predefined styles
+from being loaded. This option is provided in the event that the
+user has custom styles that are not dependent on the styles
+provided by the \sty{glossaries} package. Note that if you use
+this option, you can't use the \pkgopt{style} package option. Instead
+you must either use \ics{glossarystyle}\marg{style} or
+the \gloskey[printglossary]{style} key in the
+optional argument to \ics{printglossary}.
+
\item[\pkgopt{nonumberlist}] This option will suppress the
associated number lists\iterm{number list} in the glossaries (see also
\ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}).
@@ -1733,7 +1811,7 @@ you need to remember to use \appname{xindy} not \appname{makeindex}.
The indexing style file will been given a \filetype{.xdy} extension.
The \pkgopt{xindy} package option may additionally have a
-value that is a key=value comma-separated list to override
+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}
@@ -1764,8 +1842,10 @@ 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
+(using any of the commands described in \ifmakedtx{\autoref{sec:glslink}}{\htmlref{Links to Glossary Entries}{sec:glslink}},
+\ifmakedtx{\autoref{sec:glsadd}}{\htmlref{Adding an entry to the glossary without generating text}{sec:glsadd}} or
+\ifmakedtx{\autoref{sec:crossref}}{\htmlref{Cross-Referencing
+Entries}{sec:crossref}}) will appear in the glossary. Each time an entry
is used in this way, a line is added to an associated glossary file
(\filetype{.glo}), which then needs to be converted into a
corresponding \filetype{.gls} file which contains the typeset
@@ -1864,7 +1944,9 @@ entry is a parent entry that doesn't require a description, you
can do \verb|description={\nopostdesc}|. If you want a paragraph
break in the description use \DescribeMacro{\glspar}\cs{glspar}.
However, note that not all glossary styles support multi-line
-descriptions.
+descriptions. If you are using one of the tabular-like glossary
+styles that permit multi-line descriptions, use \ics{newline}
+not \verb"\\" if you want to force a line break.
\item[{\gloskey{parent}}] The label of the parent entry. Note that
the parent entry must be defined before its sub-entries.
@@ -1881,7 +1963,7 @@ when using \ics{gls} (or one of its uppercase 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
-the first time it is used with \ics{gls} (or one of its uppercase
+the first time it is used with \ics{gls}\ifirstusetext\ (or one of its uppercase
variants). If this field is omitted, the value of the \gloskey{text}
key is used.
@@ -1889,9 +1971,11 @@ key is used.
when using \ics{glspl} (or one of its uppercase 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 \cs{glspluralsuffix} is the letter
+\dq{s}.
\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
+document text the first time it is used with \ics{glspl}\ifirstusetext\ (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
@@ -1964,7 +2048,8 @@ 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 by appending
\DescribeMacro{\glspluralsuffix}\cs{glspluralsuffix} to
-the singular form. This command defaults to \dq{s}. For example:
+the singular form. This command defaults to the letter \dq{s}.
+For example:
\begin{verbatim}
\newglossaryentry{cow}{name=cow,description={a fully grown
female of any bovine animal}}
@@ -2034,11 +2119,9 @@ are divided into Greek letters and Roman letters. Then I can
define the categories as follows:
\begin{verbatim}
\newglossaryentry{greekletter}{name={Greek letters},
-text={Greek letter},
description={\nopostdesc}}
\newglossaryentry{romanletter}{name={Roman letters},
-text={Roman letter},
description={\nopostdesc}}
\end{verbatim}
@@ -2117,7 +2200,7 @@ parent=bravo}
\DescribeMacro{\loadglsentries}
You can store all your glossary entry definitions in another
-file, and use:\\[10pt]
+file and use:\\[10pt]
\cs{loadglsentries}\oarg{type}\marg{filename}\\[10pt]
where \meta{filename} is the name of the file containing all the
\cs{newglossaryentry} commands. The optional argument
@@ -2210,7 +2293,7 @@ Note that \cs{GlsSetXdyMinRangeLength} must be used before
\end{important}
With both \appname{makeindex} and \appname{xindy}, you can replace
-separator and the closing number in the range using:\\[10pt]
+the separator and the closing number in the range using:\\[10pt]
\DescribeMacro{\glsSetSuffixF}\cs{glsSetSuffixF}\marg{suffix}\\
\DescribeMacro{\glsSetSuffixFF}\cs{glsSetSuffixFF}\marg{suffix}\\[10pt]
where the former command specifies the suffix to use for a 2 page
@@ -2285,6 +2368,14 @@ font, do:
\renewcommand*{\glstextformat}[1]{\textsf{#1}}
\end{verbatim}
+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
+entry can be used without affecting the \firstuseflag\ (for example,
+when used with \cs{glslink}). See \ifmakedtx{\autoref{sec:glsunset}}{\htmlref{later}{sec:glsunset}} for
+commands that unset or reset this conditional.
+
\DescribeMacro{\glslink}
The command:\\[10pt]
\cs{glslink}\oarg{options}\marg{label}\marg{text}\\[10pt]
@@ -2318,13 +2409,14 @@ and use that command.
In this document, the standard formats refer to the standard text
block commands such as \ics{textbf} or \ics{emph} or any of the
-commands listed in Table~\ref{tab:hyperxx}.
+commands listed in \tableref{tab:hyperxx}.
\begin{important}
If you use \appname{xindy} instead of \appname{makeindex}, you
must specify any non-standard formats that you want to use
with the \gloskey[glslink]{format} key using
-\ics{GlsAddXdyAttribute}\marg{name}. For example
+\ics{GlsAddXdyAttribute}\marg{name}. So if you use
+\appname{xindy} with the above example, you would need to add:
\begin{verbatim}
\GlsAddXdyAttribute{textbfem}
\end{verbatim}
@@ -2341,7 +2433,7 @@ If you are using hyperlinks and you want to change the font of the
hyperlinked location, don't use \ics{hyperpage} (provided by the
\isty{hyperref} package) as the locations may not refer to a page
number. Instead, the \sty{glossaries} package provides number
-formats listed in Table~\ref{tab:hyperxx}.
+formats listed in \tableref{tab:hyperxx}.
\begin{table}[htbp]
\caption{Predefined Hyperlinked Location Formats}
@@ -2375,7 +2467,7 @@ command called, say, \cs{hyperbsf}:
\newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}}
\end{verbatim}
and then use \texttt{hyperbsf} as the value for the \gloskey{format}
-key.\ifmakedtx{ (See also \autoref{sec:printglos}.)}{}
+key.\ifmakedtx{ (See also \autoref{sec:code:printglos}.)}{}
Remember that if you use \appname{xindy}, you will need to add
this to the list of location attributes:
\begin{verbatim}
@@ -2407,9 +2499,9 @@ 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}. If the entry has been marked as having
-been used, the value of the \gloskey{text} key will be used, otherwise
+been used\ifirstuseflag, 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
+On completion, \cs{gls} will mark the entry's first use flag\ifirstuseflag\ as
used.
There are two uppercase variants:\\[10pt]
@@ -2418,7 +2510,7 @@ There are two uppercase variants:\\[10pt]
and\\[10pt]
\DescribeMacro{\GLS}
\cs{GLS}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
-which make the first letter of the link or all the link text
+which make the first letter of the link text or all the link text
uppercase, respectively.
The final optional argument \meta{insert}, allows you to insert
@@ -2447,8 +2539,9 @@ a starred version that disable the hyperlink.
\DescribeMacro{\glstext}The command:\\[10pt]
\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. Unlike \cs{gls}, the inserted text \meta{insert}
+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.
There are also analogous commands:\\[10pt]
@@ -2463,8 +2556,8 @@ the hyperlink.
\cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
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.
+to the end of the link text and does not affect the
+\firstuseflag.
There are also analogous commands:\\[10pt]
\DescribeMacro{\Glsfirst}
@@ -2567,15 +2660,16 @@ the hyperlink.
The format of the \term{link text} for \ics{gls}, \ics{glspl}
and their uppercase variants is governed by two commands:
\DescribeMacro{\glsdisplayfirst}\cs{glsdisplayfirst}, which is used the
-first time a glossary entry is used in the text and
+first time a glossary entry is used\ifirstuse\ in the text and
\DescribeMacro{\glsdisplay}\cs{glsdisplay}, which is used subsequently.
Both commands take four arguments: the first is either the singular or
plural form given by the \gloskey{text}, \gloskey{plural},
-\gloskey{first} or \gloskey{firstplural} keys (used when the term was
+\gloskey{first} or \gloskey{firstplural} keys (set when the term was
defined) depending on context; the second argument is the term's
-description (as supplied by the \gloskey{description} key); the third
+description (as supplied by the \gloskey{description} or
+\gloskey{descriptionplural} keys); the third
argument is the symbol associated with the term (as supplied by the
-\gloskey{symbol} key) and the fourth argument is the additional text
+\gloskey{symbol} or \gloskey{symbolplural} keys) and the fourth argument is the additional text
supplied in the final optional argument to \cs{gls} or
\cs{glspl} (or their uppercase variants). The default definitions
of \cs{glsdisplay} and \cs{glsdisplayfirst} simply
@@ -2600,7 +2694,7 @@ description={The length between two points},
symbol={km}}
\end{verbatim}
and now suppose you want \verb|\gls{distance}| to produce
-\dq{distance (km)} on first use, then you can redefine
+\dq{distance (km)} on \firstuse, then you can redefine
\cs{glsdisplayfirst} as follows:
\begin{verbatim}
\renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)}
@@ -2609,7 +2703,7 @@ Note that the additional text is placed after \verb|#1|, so
\verb|\gls{distance}['s]| will produce \dq{distance's (km)}
rather than \dq{distance (km)'s} which looks a bit odd (even though
it may be in the context of \dq{the distance (km) is measured between
-the two points} --- but in this instance it may be better not to
+the two points} --- but in this instance it would be better not to
use a contraction).
Note also that all of the \term{link text} will be formatted according
@@ -2625,9 +2719,11 @@ If you have multiple glossaries, changing \cs{glsdisplayfirst} and
glossaries appear when using the commands \cs{gls}, \cs{glspl} and their
uppercase variants. If you only
want the change to affect entries for a given glossary, then you need
-to use \DescribeMacro{\defglsdisplay}\cs{defglsdisplay} and
-\DescribeMacro{\defglsdisplayfirst}\cs{defglsdisplayfirst} instead
-of redefining \cs{glsdisplay} and \cs{glsdisplayfirst}.
+to use\\[10pt]
+\DescribeMacro{\defglsdisplay}\cs{defglsdisplay}\oarg{type}\marg{definition}\\[10pt]
+and\\[10pt]
+\DescribeMacro{\defglsdisplayfirst}\cs{defglsdisplayfirst}\oarg{type}\marg{definition}\\[10pt]
+instead of redefining \cs{glsdisplay} and \cs{glsdisplayfirst}.
Both \cs{defglsdisplay} and \cs{defglsdisplayfirst} take two arguments:
the first (which is optional) is the glossary's label\footnote{\texttt{main} for the main
@@ -2640,7 +2736,7 @@ redefined above.
For example, suppose you have created a new glossary called
\texttt{notation} and you want to change the way the entry is
-displayed on first use so that it includes the symbol, you can
+displayed on \firstuse\ so that it includes the symbol, you can
do:
\begin{verbatim}
\defglsdisplayfirst[notation]{#1#4 (denoted #3)}
@@ -2790,8 +2886,7 @@ default text for the \dq{see} tag is given by \ics{seename}.
The commands described in this section display entry details without
adding any information to the glossary. They don't use
\cs{glstextformat}, they don't have any optional arguments,
-they don't affect the flag that determines if the term has been
-used and, apart from \ics{glshyperlink}, they don't produce
+they don't affect the \firstuseflag\ and, apart from \ics{glshyperlink}, they don't produce
hyperlinks.
\par\vskip10pt\noindent
\DescribeMacro{\glsentryname}\cs{glsentryname}\marg{label}\\
@@ -2814,13 +2909,13 @@ entry given by \meta{label}, as specified by the \gloskey{plural} key.
\par\vskip10pt\noindent
\DescribeMacro{\glsentryfirst}\cs{glsentryfirst}\marg{label}\\
\DescribeMacro{\Glsentryfirst}\cs{Glsentryfirst}\marg{label}\par\vskip10pt\noindent
-These commands display the first use text for the glossary entry
+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.
\par\vskip10pt\noindent
\DescribeMacro{\glsentryfirstplural}\cs{glsentryfirstplural}\marg{label}\\
\DescribeMacro{\Glsentryfirstplural}\cs{Glsentryfirstplural}\marg{label}\par\vskip10pt\noindent
-These commands display the plural form of the first use text for the
+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.
@@ -3118,7 +3213,7 @@ do this. You can redefine \ics{thepage} as follows:
\renewcommand*{\thepage}{\Numberstring{page}}
\end{verbatim}
This gets expanded to \verb|\protect \Numberstringnum |\marg{n}
-where \meta{n} is the page number. This means that you need to
+where \meta{n} is the Arabic page number. This means that you need to
define a new location that has that form:
\begin{verbatim}
\GlsAddXdyLocation{Numberstring}{:sep "\string\protect\space
@@ -3158,8 +3253,9 @@ user defined location names (as specified by
\texttt{see} (cross-referenced entries).
This ordering can be changed using:\\[10pt]
\DescribeMacro{\GlsSetXdyLocationClassOrder}
-\cs{GlsSetXdyLocationClassOrder}\\[10pt]
-where each location name is delimited by double quote marks.
+\cs{GlsSetXdyLocationClassOrder}\marg{location names}\\[10pt]
+where each location name is delimited by double quote marks and
+separated by white space.
For example:
\begin{verbatim}
\GlsSetXdyLocationClassOrder{
@@ -3264,15 +3360,20 @@ can identify the list of acronyms by the command
\DescribeMacro{\acronymtype}\cs{acronymtype} which is set to
\texttt{acronym}, if the \pkgopt{acronym} option has been used,
otherwise it is set to \texttt{main}.
+
+\begin{important}
+All glossaries must be defined before \ics{makeglossaries} to
+ensure that the relevant output files are opened.
+\end{important}
\ifmakedtx{}{\toTop}
\subsection{Acronyms}
\label{sec:acronyms}
\DescribeMacro{\newacronym}
-As you may have noticed in \ifmakedtx{\autoref{sec:newglosentry}}{\htmlref{Defining Glossary Entries}{sec:newglosentry}}, when you
+You may have noticed in \ifmakedtx{\autoref{sec:newglosentry}}{\htmlref{Defining Glossary Entries}{sec:newglosentry}} that 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
+the term is first used\ifirstuse\ in the document. This provides a useful
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]
@@ -3320,7 +3421,7 @@ plural={IDNs},
firstplural={identification numbers (IDNs)}}
\end{verbatim}
so \verb|\gls{idn}| will produce \dq{identification number (IDN)} on
-first use and \dq{IDN} on subsequent uses.
+\firstuse\ and \dq{IDN} on subsequent uses.
This section describes acronyms that have been defined using
\cs{newacronym}. If you prefer to define all your acronyms using
@@ -3333,37 +3434,44 @@ formats as well as the way that the link text is displayed (see
Likewise you should ignore the package option \pkgopt{shortcuts}
and 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
-\DescribeMacro{\acronymfont}\cs{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{you will need to load a
-package, such as \sty{relsize}, that defines \cs{smaller} if you use
-this option.} 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.
-
-If you want to display the acronym in another font, for example,
-emphasized, then use the \pkgopt{smaller} package option and
-redefine \ics{acronymfont} to use the required font. For example:
+\ics{newacronym}.
+
+If you use any of the package options \pkgopt{smallcaps},
+\pkgopt{smaller}, \pkgopt{description} or
+\pkgopt{footnote}, the acronyms will be displayed in the document
+using:\\[10pt]
+\DescribeMacro{\acronymfont}\cs{acronymfont}\marg{text}\\[10pt]
+and\\[10pt]
+\DescribeMacro{\firstacronymfont}\cs{firstacronymfont}\marg{text}\\[10pt]
+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
+the \pkgopt{smaller} package option and redefine \cs{acronymfont}
+and \cs{firstacronymfont} as required. For example, if you want
+acronyms in a normal font on first use and emphasized on
+subsequent use, do:
\begin{verbatim}
\usepackage[smaller]{glossaries}
+\renewcommand*{\firstacronymfont}[1]{#1}
\renewcommand*{\acronymfont}[1]{\emph{#1}}
\end{verbatim}
-Where \cs{acronymfont} is available,
-\DescribeMacro{\firstacronymfont}\cs{firstacronymfont} is also
-available. By default, this simply uses \cs{acronymfont}, but it
-can be redefined to change the way the acronym is displayed on
-first use.
+(Note that it is for this reason that the \isty{relsize} package
+is not automatically loaded when selecting the
+\pkgopt{smaller} package option.)
+
+\Tableref{tab:acronymsettings} lists the package options that govern
+the acronym styles 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
+\cs{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{you will need to load
+a package, such as \sty{relsize}, that defines \cs{smaller} if you
+use this option.} otherwise \cs{acronymfont} simply displays its
+argument in the surrounding font.
\begin{table}[htbp]
\caption{Package options governing \cs{newacronym} and how the
@@ -3438,7 +3546,7 @@ to override the defaults. For example:
\newacronym[\glslongpluralkey={diagonal matrices}]{dm}{DM}{diagonal
matrix}
\end{verbatim}
-If the first use uses the plural form, \verb|\glspl{dm}| will
+If the \firstuse\ uses the plural form, \verb|\glspl{dm}| will
display: diagonal matrices (DMs).
Each of the package options \pkgopt{smallcaps}, \pkgopt{smaller},
@@ -3454,7 +3562,7 @@ glossary type.
\begin{description}
\item[\pkgopt{description},\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{}
-When these two package options are used together, the first use displays
+When these two package options are used together, the \firstuse\ displays
the entry as:\\[10pt]
\cs{firstacronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long}
\\[10pt]
@@ -3479,7 +3587,7 @@ remember to protect fragile commands when defining acronyms.
\item[\pkgopt{dua}]\ifmakedtx{\mbox{}\par}{}
The \pkgopt{dua} package option always displays the expanded
form and so may not be used with \pkgopt{footnote}, \pkgopt{smaller} or
-\pkgopt{smallcaps}. Both first use and subsequent use displays the
+\pkgopt{smallcaps}. Both \firstuse\ and subsequent use displays the
entry in the form:\\[10pt]
\meta{long}\meta{insert}\\[10pt]
If the \pkgopt{description} package option is also used, the
@@ -3497,7 +3605,7 @@ short form (unless overridden by the \gloskey{sort} key in
the optional argument of \ics{newacronym}).
\item[\pkgopt{description}]\ifmakedtx{\mbox{}\par}{}
-This package option displays the entry on first use as:\\[10pt]
+This package option displays the entry on \firstuse\ as:\\[10pt]
\meta{long}\meta{insert} (\cs{firstacronymfont}\marg{abbrv})\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
@@ -3526,7 +3634,7 @@ override this using the \gloskey{sort} key in the optional
argument to \ics{newacronym}.
\item[\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{}
-This package option displays the entry on first use as:\\[10pt]
+This package option displays the entry on \firstuse\ as:\\[10pt]
\cs{firstacronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long}\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
@@ -3537,15 +3645,15 @@ package additionally implements the option
\ipkgopt[description]{sanitize}\verb|sanitize={description=false}|, so
remember to protect fragile commands when defining acronyms.
-Note that on first use, it is the long form in the footnote that
+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. It is possible to change this to make the acronym
-on first use have the hyperlink instead of the footnote, but
+on \firstuse\ have the hyperlink instead of the footnote, but
since the footnote marker will also be a hyperlink, you will
have two hyperlinks in immediate succession. This can be
ambiguous where the hyperlinks are coloured rather than boxed.
-The code required to change the first use to make the
+The code required to change the \firstuse\ to make the
acronym a hyperlink is as follows:
\begin{verbatim}
\defglsdisplayfirst[\acronymtype]{%
@@ -3557,12 +3665,12 @@ acronym a hyperlink is as follows:
(i.e.\ commands whose name contains an \verb|@| character), so
if this code is place in a \texttt{.tex} file it needs to be
placed within a \cs{makeatletter} \ldots\ \cs{makeatother} pair.
-(See \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=atsigns}
+(See \ifmakedtx{\url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=atsigns}}{\htmladdnormallink{\cs{@} and \texttt{@} in macro names}{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=atsigns}}
for further details.)
\item[\pkgopt{smallcaps}]\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]
+have been set, this option displays the entry on \firstuse\ as:\\[10pt]
\meta{long}\meta{insert} (\cs{firstacronymfont}\marg{abbrv})\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
@@ -3582,7 +3690,7 @@ 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]
+have been set, this option displays the entry on \firstuse\ as:\\[10pt]
\meta{long}\meta{insert} (\cs{firstacronymfont}\marg{abbrv})\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt]
@@ -3603,7 +3711,7 @@ 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{smaller},
\pkgopt{footnote}, \pkgopt{dua} or \pkgopt{description} are used,
-then on first use the entry is displayed as:\\[10pt]
+then on \firstuse\ the entry is displayed as:\\[10pt]
\meta{long} (\meta{abbrv})\meta{insert}\\[10pt]
while subsequent use displays the entry as:\\[10pt]
\meta{abbrv}\meta{insert}\\[10pt]
@@ -3626,7 +3734,7 @@ as follows:
\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}\\
\DescribeMacro{\ACRshort}
\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
-Print the abbreviated version with a hyperlink (if necessary) to the
+Print the abbreviated version with (if required) a hyperlink to the
relevant entry in the glossary. This is usually equivalent to
\ics{glstext} (or its uppercase variants) but may additionally
put the link text within the argument to \ics{acronymfont}.
@@ -3637,7 +3745,7 @@ put the link text within the argument to \ics{acronymfont}.
\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}\\
\DescribeMacro{\ACRlong}
\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
-Print the long version with a hyperlink (if necessary) to the
+Print the long version with (if required) a hyperlink to the
relevant entry in the glossary. This is may be equivalent to
\ics{glsdesc}, \ics{glssymbol} or \ics{glsfirst} (or their uppercase
variants), depending on package options.
@@ -3649,7 +3757,7 @@ variants), depending on package options.
\DescribeMacro{\ACRfull}
\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert}\\[10pt]
Print the long version followed by the abbreviation in brackets
-with a hyperlink (if necessary) to the
+with (if required) a hyperlink to the
relevant entry in the glossary.
Note that if you change the definition of \ics{newacronym}, you
@@ -3692,12 +3800,88 @@ produce all upper case text.
\ifmakedtx{}{\toTop}
+\subsubsection{Upgrading From the glossary Package}
+Users of the obsolete \isty{glossary} package may recall that
+the syntax used to define new acronyms has changed with the
+replacement \sty{glossaries} package. In addition, the old
+\isty{glossary} package created the command
+\cs{}\meta{acr-name} when defining the acronym \meta{acr-name}.
+
+In order to facilitate migrating from the old package to the new
+one, the \isty{glossaries} package\footnote{as from version 1.18}
+provides the command:\\[10pt]
+\DescribeMacro{\oldacronym}\cs{oldacronym}\oarg{label}\marg{abbrv}\marg{long}\marg{key-val list}\\[10pt]
+This uses the same syntax as the \isty{glossary} package's
+method of defining acronyms. It is equivalent to:\\[10pt]
+\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}\\[10pt]
+In addition, \ics{oldacronym} also defines the commands
+\cs{}\meta{label}, which is equivalent to \ics{gls}\marg{label},
+and \cs{}\meta{label}\texttt{*}, which is equivalent to
+\ics{Gls}\marg{label}. If \meta{label} is omitted, \meta{abbrv}
+is used. Since commands names must consist only of alphabetical
+characters, \meta{label} must also only consist of alphabetical
+characters. Note that \cs{}\meta{label} doesn't allow you to use
+the first optional argument of \ics{gls} or \ics{Gls} --- you will
+need to explicitly use \ics{gls} or \ics{Gls} to change the
+settings.
+
+\begin{important}
+Recall that, in general, \LaTeX\ ignores spaces following command
+names consisting of alphabetical characters. This is also true for
+\cs{}\meta{label} unless you additionally load the
+\isty{xspace} package.
+\end{important}
+
+The \isty{glossaries} package doesn't load the \isty{xspace} package
+since there are both advantages and disadvantages to using
+\ics{xspace} in \cs{}\meta{label}. If you don't use the
+\isty{xspace} package you need to explicitly force a space using
+\verb*"\ " (backslash space) however you can follow \cs{}\meta{label}
+with additional text in square brackets (the final optional
+argument to \ics{gls}). If you use the \isty{xspace} package
+you don't need to escape the spaces but you can't use
+the optional argument to insert text (you will have to explicitly
+use \ics{gls}).
+
+To illustrate this, suppose I define the acronym \dq{abc} as
+follows:
+\begin{verbatim}
+\oldacronym{abc}{example acronym}{}
+\end{verbatim}
+This will create the command \cs{abc} and its starred version
+\cs{abc*}. \Tableref{tab:xspace} illustrates the effect of
+\cs{abc} (on subsequent use) according to whether or not the
+\isty{xspace} package has been loaded. As can be seen from the
+final row in the table, the \isty{xspace} package prevents the
+optional argument from being recognised.
+
+\begin{table}[htbp]
+\caption[The effect of using xspace]{The effect of using
+\sty{xspace} with \cs{oldacronym}}
+\label{tab:xspace}
+\vskip\baselineskip
+\centering
+\begin{tabular}{lll}
+\bfseries Code & \bfseries With \sty{xspace} &
+\bfseries Without \sty{xspace}\\
+\verb|\abc.| & abc. & abc.\\
+\verb|\abc xyz| & abc xyz & abcxyz\\
+\verb|\abc\ xyz| & abc xyz & abc xyz\\
+\verb|\abc* xyz| & Abc xyz & Abc xyz\\
+\verb|\abc['s] xyz| & abc ['s] xyz & abc's xyz
+\end{tabular}
+\par
+\end{table}
+
+\ifmakedtx{}{\toTop}
+
\subsection{Unsetting and Resetting Entry Flags}
+\label{sec:glsunset}
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
+entry\ifirstuse. 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}\\
@@ -3706,7 +3890,21 @@ while the latter can be achieved by one of the following commands:\\[10pt]
\DescribeMacro{\glsunset}\cs{glsunset}\marg{label}\\
\DescribeMacro{\glslocalunset}\cs{glslocalunset}\marg{label}
\\[10pt]
-You can determine whether an entry has been used using:\\[10pt]
+You can also reset or unset all entries for a given glossary or list of
+glossaries using:\\[10pt]
+\DescribeMacro{\glsresetall}\cs{glsresetall}\oarg{glossary list}\\
+\DescribeMacro{\glslocalresetall}\cs{glslocalresetall}\oarg{glossary list}\\
+\DescribeMacro{\glsunsetall}\cs{glsunsetall}\oarg{glossary list}\\
+\DescribeMacro{\glslocalunsetall}\cs{glslocalunsetall}\oarg{glossary list}\\[10pt]
+where \meta{glossary list} is a comma-separated list of
+glossary labels. If omitted, all defined glossaries are assumed.
+For example, to reset all entries in the main glossary and the
+list of acronyms:
+\begin{verbatim}
+\glsresetall[main,acronym]
+\end{verbatim}
+
+You can determine whether an entry's first use flag is set using:\\[10pt]
\DescribeMacro{\ifglsused}
\cs{ifglsused}\marg{label}\marg{true part}\marg{false part}\\[10pt]
where \meta{label} is the label of the required entry. If the
@@ -3723,8 +3921,115 @@ symbol; some styles are not designed for hierarchical entries,
so they display sub-entries in the same way as they display top
level entries; some styles are designed for homographs, so they
ignore the name for sub-entries. You should therefore pick a style
-that suits your type of glossary.
-The predefined styles are as follows:
+that suits your type of glossary. See \tableref{tab:styles} for
+a summary of the available styles.
+
+\begin{table}[htbp]
+\caption[Glossary Styles]{Glossary Styles. An asterisk in the style
+name indicates anything that matches that doesn't match any
+previously listed style (e.g.\ \texttt{long3col*}
+matches \glostyle{long3col}, \glostyle{long3colheader},
+\glostyle{long3colborder} and \glostyle{long3colheaderborder}).
+A maximum level of 0 indicates a flat glossary (sub-entries
+are displayed in the same way as main entries). Where the maximum
+level is given as --- there is no limit, but note that
+\appname{makeindex} imposes a limit of 2 sub-levels. If the
+homograph column is checked, then the name is not displayed for
+sub-entries. If the symbol column is checked, then the symbol will
+be displayed if it has been defined.}
+\label{tab:styles}
+\vskip\baselineskip
+\centering
+\begin{tabular}{lccc}
+\bfseries Style & \bfseries Maximum Level &
+\bfseries Homograph & \bfseries Symbol\\
+\ttfamily listdotted & 0 & & \\
+\ttfamily sublistdotted & 1 & & \\
+\ttfamily list* & 1 & \tick & \\
+\ttfamily altlist* & 1 & \tick & \\
+\ttfamily long3col* & 1 & \tick & \\
+\ttfamily long4col* & 1 & \tick & \tick \\
+\ttfamily altlong4col* & 1 & \tick & \tick \\
+\ttfamily long* & 1 & \tick & \\
+\ttfamily super3col* & 1 & \tick & \\
+\ttfamily super4col* & 1 & \tick & \tick \\
+\ttfamily altsuper4col* & 1 & \tick & \tick \\
+\ttfamily super* & 1 & \tick & \\
+\ttfamily index* & 2 & & \tick\\
+\ttfamily treenoname* & --- & \tick & \tick\\
+\ttfamily tree* & --- & & \tick\\
+\ttfamily alttree* & --- & & \tick
+\end{tabular}
+\par
+\end{table}
+
+The glossary style can be set using the \pkgopt{style} package option
+or using the \gloskey[printglossary]{style} key in the optional
+argument to \ics{printglossary} or using the command:\\[10pt]
+\DescribeMacro{\glossarystyle}\cs{glossarystyle}\marg{style-name}\\[10pt]
+The tabular-like styles that allow multi-line descriptions and page
+lists use the length \DescribeMacro{\glsdescwidth}\cs{glsdescwidth}
+to set the width of the description column and the length
+\DescribeMacro{\glspagelistwidth}\cs{glspagelistwidth} to set the
+width of the page list column.\footnote{these lengths will not be
+available if you use both the \pkgopt{nolong} and \pkgopt{nosuper}
+package options or if you use the \pkgopt{nostyles} package option.}
+These will need to be changed using \cs{setlength} if the glossary
+is too wide. Note that the \glostyle{long4col} and
+\glostyle{super4col} styles (and their header and border variations)
+don't use these lengths as they are designed for single line
+entries. Instead you should use the analogous \glostyle{altlong4col}
+and \glostyle{altsuper4col} styles. If you want to
+explicitly create a line-break within a multi-line description in
+a tabular-like style you should use \ics{newline} instead of
+\verb|\\|.
+
+Note that if you use the \gloskey[printglossary]{style} key in the
+optional argument to \ics{printglossary}, it will override any
+previous style settings for the given glossary, so if, for example,
+you do
+\begin{verbatim}
+\renewcommand*{\glsgroupskip}{}
+\printglossary[style=long]
+\end{verbatim}
+then the new definition of \ics{glsgroupskip} will not have an affect
+for this glossary, as \cs{glsgroupskip} is redefined by
+\verb|style=long|. Likewise, \ics{glossarystyle} will also
+override any previous style definitions, so, again
+\begin{verbatim}
+\renewcommand*{\glsgroupskip}{}
+\glossarystyle{long}
+\end{verbatim}
+will reset \cs{glsgroupskip} back to its default definition for the
+named glossary style (\glostyle{long} in this case). If you want to
+modify the styles, either use \ics{newglossarystyle} (described
+in the next section) or make the modifications after
+\ics{glossarystyle}, e.g.:
+\begin{verbatim}
+\glossarystyle{long}
+\renewcommand*{\glsgroupskip}{}
+\end{verbatim}
+
+ \changes{1.03}{2007 July 4}{'glspostdescription added}
+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
+will need to redefine \cs{glspostdescription} before the glossary is
+displayed. Alternatively, you can suppress it for a given entry
+by placing \ics{nopostdesc} in the entry's description.
+\ifmakedtx{}{\toTop}
+
+\subsubsection{List Styles}
+\label{sec:liststyles}
+
+The styles described in this section are all defined in the package
+\isty{glossary-list}. Since they all use the \envname{description}
+environment, they are governed by the same parameters as that
+environment. These styles all ignore the entry's symbol. Note that
+these styles will not be available if you use either the
+\pkgopt{nolist} or \pkgopt{nostyles} package options.
\begin{description}
\item[list] The \glostyle{list} style uses the \envname{description}
@@ -3742,7 +4047,7 @@ child entry. Groups are separated using \cs{indexspace}.
\glostyle{listgroup} but has a navigation line at the start of
the glossary with links to each group that is present in the
glossary. This requires an additional run through \LaTeX\ to ensure
-the group information is up-to-date. In the navigation line, each
+the group information is up to date. In the navigation line, each
group is separated
by \DescribeMacro{\glshypernavsep}\cs{glshypernavsep} which
defaults to a vertical bar with a space on either side. For example,
@@ -3772,14 +4077,31 @@ groups. The navigation line is the same as that for
\glostyle{listhypergroup}, described above.
\item[listdotted] This style uses the \envname{description}
-environment. Each entry starts with \verb|\item[]|, followed by the
-name followed by a dotted line, followed by the description. Note that
-this style ignores both the \term{number list} and the symbol. The
-length \DescribeMacro{\glslistdottedwidth}\cs{glslistdottedwidth}
-governs where the description should start.\footnote{This style was
-supplied by Axel~Menzel.} This is a flat style, so child
+environment.\footnote{This style was supplied by Axel~Menzel.} Each
+entry starts with \verb|\item[]|, followed by the name followed by a
+dotted line, followed by the description. Note that this style
+ignores both the \term{number list} and the symbol. The length
+\DescribeMacro{\glslistdottedwidth}\cs{glslistdottedwidth} governs
+where the description should start. This is a flat style, so child
entries are formatted in the same way as the parent entries.
+\item[sublistdotted] This is a variation on the \glostyle{listdotted}
+style designed for hierarchical glossaries. The main entries
+have just the name displayed. The sub entries are displayed in
+the same manner as \glostyle{listdotted}.
+\end{description}
+\ifmakedtx{}{\toTop}
+
+\subsubsection{Longtable Styles}
+\label{sec:longstyles}
+
+The styles described in this section are all defined in the package
+\isty{glossary-long}. Since they all use the \envname{longtable}
+environment, they are governed by the same parameters as that
+environment. Note that these styles will not be available if you
+use either the \pkgopt{nolong} or \pkgopt{nostyles} package options.
+
+\begin{description}
\item[long] The \glostyle{long} style uses the \envname{longtable}
environment (defined by the \isty{longtable} package). It has two
columns: the first column contains the entry's name and the second
@@ -3859,7 +4181,23 @@ page lists.
\item[altlong4colheaderborder] The \glostyle{altlong4colheaderborder}
style is like \glostyle{long4colheaderborder} but allows multi-line
descriptions and page lists.
+\end{description}
+\ifmakedtx{}{\toTop}
+
+\subsubsection{Supertabular Styles}
+\label{sec:superstyles}
+The styles described in this section are all defined in the package
+\isty{glossary-super}. Since they all use the \envname{supertabular}
+environment, they are governed by the same parameters as that
+environment. Note that these styles will not be available if you
+use either the \pkgopt{nosuper} or \pkgopt{nostyles} package options.
+In general, the \envname{longtable} environment is better, but there
+are some circumstances where it is better to use
+\envname{supertabular}.\footnote{e.g.\ with the \isty{flowfram}
+package.}
+
+\begin{description}
\item[super] The \glostyle{super} style uses the \envname{supertabular}
environment (defined by the \isty{supertabular} package). It has two
columns: the first column contains the entry's name and the second
@@ -3940,14 +4278,28 @@ page lists.
\item[altsuper4colheaderborder] The \glostyle{altsuper4colheaderborder}
style is like \glostyle{super4colheaderborder} but allows multi-line
descriptions and page lists.
+\end{description}
+\ifmakedtx{}{\toTop}
+
+\subsubsection{Tree-Like Styles}
+\label{sec:treestyles}
-\item[index] The \glostyle{index} style is similar to the
-way indices are usually formatted in that it has a
-hierarchical structure up to three levels. The name is typeset in
-bold, and if the symbol is present it is set in parentheses after
-the name and before the description. Sub-entries are indented and
-also include the name, the symbol (if present) and the description.
-Groups are separated using \ics{indexspace}.
+The styles described in this section are all defined in the package
+\isty{glossary-tree}. These styles are designed for hierarchical
+glossaries but can also be used with glossaries that don't have
+sub-entries. These styles will display the entry's symbol if it
+exists. Note that these styles will not be available if you
+use either the \pkgopt{notree} or \pkgopt{nostyles} package options.
+
+\begin{description}
+\item[index] The \glostyle{index} style is similar to the way
+indices are usually formatted in that it has a hierarchical
+structure up to three levels (the main level plus two sub-levels).
+The name is typeset in bold, and if the symbol is present it is set
+in parentheses after the name and before the description.
+Sub-entries are indented and also include the name, the symbol
+in brackets (if present) and the description. Groups are separated
+using \ics{indexspace}.
\item[indexgroup] The \glostyle{indexgroup} style is similar to
the \glostyle{index} style except that each group has a heading.
@@ -4013,60 +4365,6 @@ groups. The navigation line is the same as that for
\end{description}
-The glossary style can be set using the \pkgopt{style} package option
-or using the \gloskey[printglossary]{style} key in the optional
-argument to \ics{printglossary} or using the command:\\[10pt]
-\DescribeMacro{\glossarystyle}\cs{glossarystyle}\marg{style-name}\\[10pt]
-The tabular-like styles that allow multi-line descriptions and page
-lists use the length \DescribeMacro{\glsdescwidth}\cs{glsdescwidth} to
-set the width of the description column and the length
-\DescribeMacro{\glspagelistwidth}\cs{glspagelistwidth} to set the
-width of the page list column. These will need to be changed using
-\cs{setlength} if the glossary is too wide. Note that the
-\glostyle{long4col} and \glostyle{super4col} styles (and their header and border
-variations) don't use these lengths as they are designed for single
-line entries. Instead you should use the analogous
-\glostyle{altlong4col} and \glostyle{altsuper4col} styles.
-Note that if you want to explicitly create a line-break within
-a multi-line description you should use \ics{newline} instead
-of \verb|\\|.
-
-Note that if you use the \gloskey[printglossary]{style} key in the
-optional argument to \ics{printglossary}, it will override any
-previous style settings for the given glossary, so if, for example,
-you do:
-\begin{verbatim}
-\renewcommand*{\glsgroupskip}{}
-\printglossary[style=long]
-\end{verbatim}
-The new definition of \ics{glsgroupskip} will not have an affect
-for this glossary, as \cs{glsgroupskip} is redefined by
-\verb|style=long|. Likewise, \ics{glossarystyle} will also
-override any previous style definitions, so, again:
-\begin{verbatim}
-\renewcommand*{\glsgroupskip}{}
-\glossarystyle{long}
-\end{verbatim}
-will reset \cs{glsgroupskip} back to its default definition for the
-named glossary style (\glostyle{long} in this case). If you want to
-modify the styles, either use \ics{newglossarystyle} (described
-in the next section) or make the modifications after
-\ics{glossarystyle}, e.g.:
-\begin{verbatim}
-\glossarystyle{long}
-\renewcommand*{\glsgroupskip}{}
-\end{verbatim}
-
- \changes{1.03}{2007 July 4}{'glspostdescription added}
-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
-will need to redefine \cs{glspostdescription} before the glossary is
-displayed. Alternatively, you can suppress it for a given entry
-by placing \ics{nopostdesc} in the entry's description.
-
\ifmakedtx{}{\toTop}
\subsection{Defining your own glossary style}
@@ -4103,20 +4401,38 @@ glossary style redefines \cs{glossaryheader} to do a header row.
\item
\DescribeMacro{\glsgroupheading}
-\cs{glsgroupheading}\marg{label}\par\noindent
-This macro indicates what to do at the start of each logical block
-within the main body of the glossary. The glossary is sub-divided into
-twenty-eight logical blocks that are determined by the first character
-of the \gloskey{sort} key (or \gloskey{name} key if the \gloskey{sort}
-key is omitted). The sub-divisions are in the following order: symbols,
-numbers, A, \ldots, Z\@. (This may be different if you use
-\appname{xindy}.) Note that the argument to \cs{glsgroupheading}
+\cs{glsgroupheading}\marg{label}\par\noindent This macro indicates
+what to do at the start of each logical block within the main body
+of the glossary. If you use \appname{makeindex} the glossary is
+sub-divided into a maximum of twenty-eight logical blocks that are
+determined by the first character of the \gloskey{sort} key (or
+\gloskey{name} key if the \gloskey{sort} key is omitted). The
+sub-divisions are in the following order: symbols, numbers, A,
+\ldots, Z\@. If you use \appname{xindy}, the sub-divisions depend on
+the language settings.
+
+Note that the argument to \cs{glsgroupheading}
is a label \emph{not} the group title. The group title can be obtained
-via \cs{glsgetgrouptitle}\marg{label}, and a navigation hypertarget can
-be created using \cs{glsnavhypertarget}\marg{label}. Most of the
-predefined glossary styles redefine \cs{glsgroupheading} to simply
-ignore its argument. The \glostyle{listhypergroup} style redefines
-\cs{glsgroupheading} as follows:
+via
+
+\DescribeMacro{\glsgetgrouptitle}\cs{glsgetgrouptitle}\marg{label}
+
+This obtains the title as follows: if
+\cs{}\meta{label}\texttt{groupname} exists, this is taken to be the
+title, otherwise the title is just \meta{label}.
+
+A navigation hypertarget can be created using
+
+\DescribeMacro{\glsnavhypertarget}\cs{glsnavhypertarget}\marg{label}\marg{text}
+
+For further details about \cs{glsnavhypertarget}, see
+\ifmakedtx{\autoref{sec:code:hypernav}}{the documented code of \isty{glossary-hypernav}
+in \texttt{glossaries.pdf}}.
+
+
+Most of the predefined glossary styles redefine \cs{glsgroupheading}
+to simply ignore its argument. The \glostyle{listhypergroup} style
+redefines \cs{glsgroupheading} as follows:
\begin{verbatim}
\renewcommand*{\glsgroupheading}[1]{%
\item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]}
@@ -4144,20 +4460,25 @@ Note that \meta{formatted name} will always be in the form
font for the entry name, regardless of the glossary style used.
Note that \meta{label} is the label used when the glossary entry
was defined via either \cs{newglossaryentry} or \cs{newacronym}.
-Each time you use a glossary entry it creates a
-link\footnote{if the document doesn't have hyperlinks enabled
-\cs{@glslink} ignores the label and simply typesets the text.}
-using \cs{@glslink}\marg{label}\marg{text} with the label
-\texttt{glo:}\meta{label}. Your
-new glossary style must therefore redefine \cs{glossaryentryfield}
-so that it uses \cs{@glstarget}\verb|{|\texttt{glo:}\meta{label}\verb|}|\marg{text}
-to ensure the hyperlinks function correctly.\footnote{again, if the
-document doesn't support hyperlinks, \cs{@glstarget} will ignore
-the label, and just typeset the text.} For example, the
+
+Each time you use a glossary entry it creates a hyperlink (if
+hyperlinks are enabled) to the relevant line in the glossary.
+Your new glossary style must therefore redefine
+\cs{glossaryentryfield} to set the appropriate target. This
+is done using
+
+\DescribeMacro{\glstarget}\cs{glstarget}\marg{label}\marg{text}
+
+where \meta{label} is the entry's label. Note that you
+don't need to worry about whether the \isty{hyperref} package has
+been loaded, as \cs{glstarget} won't create a target if
+\cs{hypertarget} hasn't been defined.
+
+For example, the
\glostyle{list} style defines \cs{glossaryentryfield} as follows:
\begin{verbatim}
\renewcommand*{\glossaryentryfield}[5]{%
-\item[\@glstarget{glo:##1}{##2}] ##3\glspostdescription\space ##5}
+\item[\glstarget{##1}{##2}] ##3\glspostdescription\space ##5}
\end{verbatim}
Note also that \meta{number list} will always be of the form\\[10pt]
@@ -4189,23 +4510,24 @@ The first argument, \meta{level}, indicates the sub-entry level.
This must be an integer from 1 (first sub-level) onwards. The
remaining arguments are analogous to those for
\ics{glossaryentryfield} described above.
-\end{description}\ifmakedtx{}{\toTop}
+\end{description}
+
+For further details of these commands, see
+\ifmakedtx{\autoref{sec:code:printglos}}{the documented code in \texttt{glossaries.pdf}}.
+\ifmakedtx{}{\toTop}
\subsubsection{Example: creating a completely new style}
If you want a completely new style, you will need to redefine all
-of the commands and environment listed above. You also need to
-take care when using internal commands (commands whose name
-contain the @ symbol). These should either be used in a \texttt{.sty}
-file or must be placed within \cs{makeatletter} and \cs{makeatother}.
+of the commands and the environment listed above.
For example, suppose you want each entry to start with a bullet point.
This means that the glossary should be placed in the \envname{itemize}
environment, so \envname{theglossary} should start and end that
environment. Let's also suppose that you don't want anything between
-the glossary groups (so \cs{glsgroupheading} and \cs{glsgroupskip}
+the glossary groups (so \ics{glsgroupheading} and \ics{glsgroupskip}
should do nothing) and suppose you don't want anything to appear
-immediately after \verb|\begin{theglossary}| (so \cs{glossaryheader}
+immediately after \verb|\begin{theglossary}| (so \ics{glossaryheader}
should do nothing). In addition, let's suppose the symbol should
appear in brackets after the name, followed by the description and
last of all the \term{number list} should appear within square brackets
@@ -4223,14 +4545,14 @@ at the end. Then you can create this new glossary style, called, say,
% set how each entry should appear:
\renewcommand*{\glossaryentryfield}[5]{%
\item % bullet point
- \@glstarget{glo:##1}{##2}% the entry name
+ \glstarget{##1}{##2}% the entry name
\space (##4)% the symbol in brackets
\space ##3% the description
\space [##5]% the number list in square brackets
}%
% set how sub-entries appear:
\renewcommand*{\glossarysubentryfield}[6]{%
- \glossaryentryfield{#2}{#3}{#4}{#5}{#6}}%
+ \glossaryentryfield{##2}{##3}{##4}{##5}{##6}}%
}
\end{verbatim}
Note that this style creates a flat glossary, where sub-entries
@@ -4328,7 +4650,7 @@ command \cs{@gls@makefirstuc}. For example:
\end{verbatim}
(Remember that command names that contain the @ character must
either be placed in packages or be placed between \cs{makeatletter}
-\cs{makeatother}.)
+and \cs{makeatother}.)
\ifmakedtx{}{\toTop}