summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-11-14 22:52:09 +0000
committerKarl Berry <karl@freefriends.org>2013-11-14 22:52:09 +0000
commit033271bfdf58e2563bd3fbdbeb0f1facfb0c02e5 (patch)
tree1ca0cddf673e09a878c83db761e4dc52c65ba48b /Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
parente537bba01fd3f3a532b7fc1f6186c24065208638 (diff)
glossaries (14nov13)
git-svn-id: svn://tug.org/texlive/trunk@32147 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex2608
1 files changed, 1970 insertions, 638 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
index 7a79a1ae440..eed1cd7749d 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -8,6 +8,7 @@
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
+\usepackage{fourier}
\ifpdf
\usepackage{mathpazo}
\usepackage[scaled=.88]{helvet}
@@ -20,12 +21,12 @@
pdftitle={User Manual for glossaries.sty},
pdfkeywords={LaTeX,package,glossary,acronyms}]{hyperref}
\usepackage{xr-hyper}
-\usepackage[xindy,nonumberlist,seeautonumberlist,toc,style=altlist]{glossaries}
+\usepackage[xindy,nonumberlist,seeautonumberlist,toc,nogroupskip,style=altlist]{glossaries}
\usepackage{glossary-inline}
\pagestyle{headings}
-\renewcommand*{\glsgroupskip}{}
+\glsnoexpandfields
\renewcommand*{\glsseeformat}[3][\seename]{%
(\xmakefirstuc{#1} \glsseelist{#2}.)%
@@ -39,9 +40,10 @@
\+\>nonumberlist,\\
seeautonumberlist,\\
toc,\\
- style=altlist]\{glossaries\}
+ style=altlist,\\
+ nogroupskip]\{glossaries\}
\end{tabbing}
-\cs{renewcommand*}\{\ics{glsgroupskip}\}\{\}\newline
+\cs{glsnoexpandfields}\newline
\cs{renewcommand*}\{\ics{glsseeformat}\}[3][\ics{seename}]\{\% \newline
(\ics{xmakefirstuc}\{\#1\} \ics{glsseelist}\{\#2\}.)\}
\end{ttfamily}
@@ -51,9 +53,9 @@
\else
% Need an extra line break in the html version
% (Don't have time to fiddle with cfg files!)
- \renewcommand*{\glossaryentryfield}[5]{%
- \item[\glsentryitem{#1}\glstarget{#1}{#2}]\mbox{}\newline
- #3\glspostdescription\space #5\newline}%
+ \renewcommand*{\glossentry}[2]{%
+ \item[\glsentryitem{#1}\glstarget{#1}{\glossentryname{#1}}]\mbox{}\newline
+ \glossentrydesc{#1}\glspostdescription\space #2\newline}%
\fi
\makeglossaries
@@ -65,62 +67,71 @@
\IndexPrologue{\chapter*{\indexname}
\markboth{\indexname}{\indexname}}
-\newglossaryentry{indexingapp}%
+\longnewglossaryentry{indexingapp}%
{
name={Indexing application},
- text={indexing application},
- description={an application (piece of software) separate from
+ text={indexing application}
+}%
+{%
+ An application (piece of software) separate from
\TeX/\LaTeX\ that collates and sorts information that has an
associated page reference. Generally the information is an index
entry but in this case the information is a glossary entry.
There are two main indexing applications that are used with \TeX:
- \protect\gls{makeindex} and \protect\gls{xindy}. These are both
- \gls{cli} applications}
+ \gls{makeindex} and \gls{xindy}. These are both
+ \gls{cli} applications.
}
-\newglossaryentry{cli}
+\longnewglossaryentry{cli}
{
name={Command Line Interface (CLI)},
first={command line interface (CLI)},
- text={CLI},
- description={an application that doesn't have a graphical user
+ text={CLI}
+}
+{%
+ An application that doesn't have a graphical user
interface. That is, an application that doesn't have any windows,
buttons or menus and can be run in a command
prompt or terminal (see
- \url{http://www.dickimaw-books.com/latex/novices/html/terminal.html})}
+ \url{http://www.dickimaw-books.com/latex/novices/html/terminal.html}).
}
-\newglossaryentry{xindy}{
-name={\appfmt{xindy}\index{xindy|htextbf}},
-sort={xindy},
-text={\protect\app{xindy}},
-description={A flexible \protect\gls{indexingapp} with multilingual
-support written in Perl}
+\longnewglossaryentry{xindy}{%
+ name={\appfmt{xindy}\index{xindy|htextbf}},
+ sort={xindy},
+ text={\protect\app{xindy}}
+}%
+{%
+ A flexible \gls{indexingapp} with multilingual
+ support written in Perl.
}
\newglossaryentry{makeindex}{%
name={\appfmt{makeindex}\index{makeindex|htextbf}},%
sort={makeindex},%
text={\protect\app{makeindex}},%
-description={An \protect\gls{indexingapp}},
+description={An \gls{indexingapp}},
}
\newglossaryentry{makeglossaries}{%
name={\appfmt{makeglossaries}\index{makeglossaries|htextbf}},%
sort={makeglossaries},%
text={\protect\app{makeglossaries}},%
-description={A \styfmt{glossaries} custom designed Perl script interface
-to \gls{xindy} and \gls{makeindex}}
+description={A custom designed Perl script interface
+to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries}
+package}
}
-\newglossaryentry{makeglossariesgui}{%
+\longnewglossaryentry{makeglossariesgui}{%
name={\appfmt{makeglossariesgui}\index{makeglossariesgui|htextbf}},%
sort={makeglossariesgui},%
-text={\protect\app{makeglossariesgui}},%
-description={A Java GUI alternative to \gls{makeglossaries} that
-also provides diagnostic tools. Home page:
-\url{http://www.dickimaw-books.com/apps/makeglossariesgui/}. Also
-available on CTAN}
+text={\protect\app{makeglossariesgui}}%
+}%
+{%
+ A Java GUI alternative to \gls{makeglossaries} that
+ also provides diagnostic tools. Home page:
+ \url{http://www.dickimaw-books.com/apps/makeglossariesgui/}. Also
+ available on CTAN.
}
\newglossaryentry{numberlist}{%
@@ -160,25 +171,29 @@ or may not be a hyperlink to the glossary}
\let\glsd\glsuseri
\let\glsation\glsuserii
-\newglossaryentry{firstuse}{%
+\longnewglossaryentry{firstuse}{%
name={First use\ifirstuse},
sort={first use},%
text={first use},%
-user1={first used},
-description={The first time a glossary entry is used (from the start of the document or after a reset) with one of the
-following commands: \ics{gls}, \ics{Gls}, \ics{GLS}, \ics{glspl},
-\ics{Glspl}, \ics{GLSpl} or \ics{glsdisp}.
-\glsseeformat{firstuseflag,firstusetext}{}\nopostdesc}%
+user1={first used}}
+{%
+ The first time a glossary entry is used (from the start of the
+ document or after a reset) with one of the
+ following commands: \ics{gls}, \ics{Gls}, \ics{GLS}, \ics{glspl},
+ \ics{Glspl}, \ics{GLSpl} or \ics{glsdisp}.
+ \glsseeformat{firstuseflag,firstusetext}{}
}
-\newglossaryentry{firstuseflag}{%
+\longnewglossaryentry{firstuseflag}{%
name={First use flag\ifirstuseflag},
sort={first use flag},%
-text={first use flag},%
-description={A conditional that determines whether or not the entry
-has been used according to the rules of \gls{firstuse}. Commands
-to unset or reset this conditional are described in
-\sectionref{sec:glsunset}}%
+text={first use flag}%
+}
+{%
+ A conditional that determines whether or not the entry
+ has been used according to the rules of \gls{firstuse}. Commands
+ to unset or reset this conditional are described in
+ \sectionref{sec:glsunset}.
}
\newglossaryentry{firstusetext}{%
@@ -191,28 +206,24 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of
\ics{glsdisp}.)\nopostdesc}%
}
-\newglossaryentry{sanitize}{%
+\longnewglossaryentry{sanitize}{%
name={Sanitize\itermdef{sanitize}},%
sort={sanitize},
text={\protect\term{sanitize}},%
user1={sanitized\protect\iterm{sanitize}},%
-user2={sanitization\protect\iterm{sanitize}},
-description={Converts command names into character sequences. That is, a command called,
-say, \cs{foo}, is converted into the sequence of characters:
-\cs{}, \texttt{f}, \texttt{o}, \texttt{o}. Depending on the font,
-the backslash character may appear as a dash when used in the
-main document text, so \cs{foo} will appear as: ---foo.
-\glspar
-When \TeX\ writes information to a file, fragile
-commands must be protected. The \gloskey{name}, \gloskey{description},
-\gloskey{symbol} and \gloskey{sort} keys all have their values written to a file,
-which means that care must be taken if those values contain fragile
-commands. There are two approaches: 1) the fragile commands must be
-protected using \ics{protect}; 2) the values are sanitized.
-Sanitizing the values gets rid of the inconvenience of having to
-protect fragile commands, but at the expense of no longer being able
-to use those values in the document. Sanitization is governed by the
-package option \pkgopt{sanitize} described in \sectionref{sec:pkgopts-general}}
+user2={sanitization\protect\iterm{sanitize}}%
+}%
+{%
+ Converts command names into character sequences. That is, a command called,
+ say, \cs{foo}, is converted into the sequence of characters:
+ \cs{}, \texttt{f}, \texttt{o}, \texttt{o}. Depending on the font,
+ the backslash character may appear as a dash when used in the
+ main document text, so \cs{foo} will appear as: ---foo.
+
+ Earlier versions of \styfmt{glossaries} used this technique to write
+ information to the files used by the indexing applications to
+ prevent problems caused by fragile commands. Now, this is only used
+ for the \gloskey{sort} key.
}
\ifpdf
@@ -246,7 +257,17 @@ package option \pkgopt{sanitize} described in \sectionref{sec:pkgopts-general}}
\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\ttfamily#1}|main}}
-\newcommand*{\samplefile}[1]{\hyperref[ex:sample#1]{\texttt{sample#1.tex}}}
+\newcounter{sample}
+\newcommand{\exitem}[2][sample]{%
+ \item[\texttt{#1#2.tex}]%
+ \refstepcounter{sample}\label{ex:#1#2}}
+
+\newenvironment{samplelist}%
+{\begin{description}}%
+{\end{description}}
+
+\newcommand*{\samplefile}[2][sample]{%
+ \hyperref[ex:#1#2]{\texttt{#1#2.tex}}}
\ifpdf
\newcommand*{\htmldoc}[2]{\qt{#1}}
@@ -258,13 +279,31 @@ package option \pkgopt{sanitize} described in \sectionref{sec:pkgopts-general}}
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for glossaries.sty v3.07}
+ \title{User Manual for glossaries.sty v4.0}
\author{Nicola L.C. Talbot\\%
\url{http://www.dickimaw-books.com/}}
- \date{2013-07-05}
+ \date{2013-11-14}
\maketitle
+\begin{important}
+Documents have varied styles when it comes to presenting glossaries
+or lists of terms or notation. People have their own preferences and
+to a large extent this is determined by the kind of information that
+needs to go in the glossary. They may just have symbols with
+terse descriptions or they may have long technical words with
+complicated descriptions. The \styfmt{glossaries} package is
+flexible enough to accommodate such varied requirements, but this
+flexibility comes at a price: a~big manual.
+
+\grimace\ If you're freaking out at the size of this manual, start with
+\texttt{glossariesbegin.pdf} (\qt{The glossaries package: a guide
+for beginnners}). You should find it in the same directory as this
+document or try \texttt{texdoc glossariesbegin.pdf}. Once you've got
+to grips with the basics, then come back to this manual to find out
+how to adjust the settings.
+\end{important}
+
\noindent
The \styfmt{glossaries} bundle comes with the following documentation:
\begin{description}
@@ -290,7 +329,7 @@ letter}{mfirstuc-manual}.
\item[\url{glossaries-code.pdf}]
Advanced users wishing to know more about the inner workings of all the
packages provided in the \styfmt{glossaries} bundle should read
-\qt{Documented Code for glossaries v3.07}.
+\qt{Documented Code for glossaries v4.0}.
This includes the documented code for the \sty{mfirstuc} package.
\item[INSTALL] Installation instructions.
@@ -307,17 +346,32 @@ If you use \sty{hyperref} and \styfmt{glossaries}, you must load
also be loaded before \styfmt{glossaries}. (If \sty{doc} is loaded,
the file extensions for the default main glossary are changed to
\filetype{gls2}, \filetype{glo2} and \filetype{.glg2} to avoid
-conflict with \sty{doc}'s changes glossary.)
+conflict with \sty{doc}'s changes
+glossary.)\hypertarget{pdflatexnote}{}%
+
+If you are using \sty{hyperref}, it's best to use \app{pdflatex}
+rather than \app{latex} (DVI format) as \appfmt{pdflatex} deals with
+hyperlinks much better. If you use the DVI format, you will
+encounter problems where you have long hyperlinks or hyperlinks in
+subscripts or superscripts. This is an issue with the DVI format not
+with \sty{glossaries}.
\end{important}
-Other documents that describe using \styfmt{glossaries} include:
+Other documents that describe using the \styfmt{glossaries} package include:
\href{http://www.dickimaw-books.com/latex/thesis/}{Using LaTeX to Write a PhD Thesis}
and
\href{http://www.latex-community.org/know-how/latex/55-latex-general/263-glossaries-nomenclature-lists-of-symbols-and-acronyms}{Glossaries,
Nomenclature, Lists of Symbols and Acronyms}.
\clearpage
+\pdfbookmark[0]{Contents}{contents}
\tableofcontents
+\clearpage
+\pdfbookmark[0]{List of Examples}{examples}
+\listofexamples
+\clearpage
+\pdfbookmark[0]{List of Tables}{tables}
+\listoftables
\clearpage
\printglossaries
@@ -335,7 +389,7 @@ terms. Only those terms used\footnote{That is, if the term has been
referenced using any of the commands described in
\sectionref{sec:glslink} and \sectionref{sec:glsadd} or via
\ics{glssee} (or the \gloskey{see} key) or commands such as
-\ics{acrshort}.} in the document will be added to the glossary.
+\ics{acrshort}.}\ in the document will be added to the glossary.
\textbf{This package replaces the \sty{glossary} package which is
now obsolete.} Please see the document \qtdocref{Upgrading from the
@@ -361,10 +415,10 @@ reason you don't want to use \gls*{makeglossaries}, you can call
\end{important}
This document uses the \styfmt{glossaries} package. For example,
when viewing the PDF version of this document in a
-hyperlinked-enabled PDF viewer (such as Adobe Reader) if
-you click on the word ``\gls{xindy}'' you'll be taken to the entry
+hyperlinked-enabled PDF viewer (such as Adobe Reader or Okular) if
+you click on the word \qt{\gls{xindy}} you'll be taken to the entry
in the glossary where there's a brief description of
-what ``\gls*{xindy}'' is.
+what \qt{\gls*{xindy}} is.
The remainder of this introductory section covers the following:
\begin{itemize}
@@ -394,19 +448,18 @@ For example, in a
\begin{prompt}
texdoc -l glossaries
\end{prompt}
-This should display the full pathname of the file
-\texttt{glossaries-code.pdf}. View the contents of that directory and
-see if it contains the \texttt{samples} subdirectory.
-
-If you can't find the sample files, they are available in the
-subdirectory \texttt{doc/latex/glossaries/samples/} in the
-\texttt{glossaries.tds.zip} archive which can be downloaded from
-\href{http://tug.ctan.org/tex-archive/macros/latex/contrib/glossaries/}{CTAN}.
-
-
-The sample documents are as follows:
-\begin{description}
-\item[minimalgls.tex]\label{ex:minimalgls} This document is a
+This should display a list of all the files in the glossaries
+documentation directory with their full pathnames.
+
+If you can't find the sample files on your computer, they are also available
+from your nearest CTAN mirror at
+\url{http://mirror.ctan.org/macros/latex/contrib/glossaries/samples/}.
+
+The sample documents are as follows\footnote{Note that although I've written
+\texttt{latex} in this section, it's better to use \texttt{pdflatex}, where
+possible, for the reasons given \hyperlink{pdflatexnote}{earlier}.}:
+\begin{samplelist}
+\exitem[minimal]{gls} 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:
@@ -420,7 +473,13 @@ latex minimalgls
your text editor or front-end. This will create the required
associated files but you will not see the glossary. If you use
PDF\LaTeX\ you will also get warnings about non-existent
- references. These warnings may be ignored on the first run.
+ references that look something like:
+\begin{verbatim}
+pdfTeX warning (dest): name{glo:aca} has been
+referenced but does not exist,
+replaced by a fixed one
+\end{verbatim}
+ 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 \sty{xkeyval} is
@@ -457,7 +516,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]\label{ex:sample4col} This document illustrates
+\exitem{4col} 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:
@@ -472,7 +531,7 @@ As before, if you don't have Perl installed, you will need to use
gap created at the start of each group. This can be suppressed
using the \pkgopt{nogroupskip} package option.
-\item[sampleAcr.tex]\label{ex:sampleAcr} This document has some
+\exitem{Acr} 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:
@@ -483,7 +542,7 @@ latex sampleAcr
latex sampleAcr
\end{prompt}
-\item[sampleAcrDesc.tex]\label{ex:sampleAcrDesc} This is similar to
+\exitem{AcrDesc} 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:
@@ -494,7 +553,7 @@ latex sampleAcrDesc
latex sampleAcrDesc
\end{prompt}
-\item[sampleDesc.tex]\label{ex:sampleDesc} This is similar to the
+\exitem{Desc} 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 contents, so
@@ -506,7 +565,16 @@ latex sampleDesc
latex sampleDesc
\end{prompt}
-\item[sample-custom-acronym.tex]\label{ex:sample-custom-acronym}
+\exitem{-FnDesc} This example
+defines a custom display format that puts the description in a
+footnote on first use.
+\begin{prompt}
+latex sample-FnDesc
+makeglossaries sample-FnDesc
+latex sample-FnDesc
+\end{prompt}
+
+\exitem{-custom-acronym}
This document illustrates how to define your own acronym style if
the predefined styles don't suit your requirements.
\begin{prompt}
@@ -515,7 +583,7 @@ makeglossaries sample-custom-acronym
latex sample-custom-acronym
\end{prompt}
-\item[sample-crossref.tex]\label{ex:sample-crossref}
+\exitem{-crossref}
This document illustrates how to cross-reference entries in the
glossary.
\begin{prompt}
@@ -524,7 +592,7 @@ makeglossaries sample-crossref
latex sample-crossref
\end{prompt}
-\item[sampleDB.tex]\label{ex:sampleDB} This document illustrates how
+\exitem{DB} 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
\gls{numberlist} suppressed and uses \ics{glsaddall} to add all
@@ -540,17 +608,17 @@ The glossary definitions are stored in the accompanying files
don't have Perl installed, you will need to use \gls{makeindex}
twice instead of a single call to \gls{makeglossaries}:
\begin{enumerate}
-\item Create the main glossary:
+\item Create the main glossary (all on one line):
\begin{prompt}
makeindex -s sampleDB.ist -t sampleDB.glg -o sampleDB.gls sampleDB.glo
\end{prompt}
-\item Create the secondary glossary:
+\item Create the secondary glossary (all on one line):
\begin{prompt}
makeindex -s sampleDB.ist -t sampleDB.nlg -o sampleDB.not sampleDB.ntn
\end{prompt}
\end{enumerate}
-\item[sampleEq.tex]\label{ex:sampleEq} This document illustrates how
+\exitem{Eq} 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 \env{equation} environment. To create
@@ -561,7 +629,7 @@ makeglossaries sampleEq
latex sampleEq
\end{prompt}
-\item[sampleEqPg.tex]\label{ex:sampleEqPg} This is similar to the
+\exitem{EqPg} This is similar to the
previous example, but the \glspl{numberlist} 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
@@ -573,7 +641,7 @@ latex sampleEqPg
latex sampleEqPg
\end{prompt}
-\item[sampleSec.tex]\label{ex:sampleSec} This document also
+\exitem{Sec} 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
@@ -585,7 +653,7 @@ latex sampleSec
latex sampleSec
\end{prompt}
-\item[sampleNtn.tex]\label{ex:sampleNtn} This document illustrates
+\exitem{Ntn} 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:
@@ -599,17 +667,17 @@ Note that if you don't have Perl installed, you will need to use
\gls{makeindex} twice instead of a single call to
\gls{makeglossaries}:
\begin{enumerate}
-\item Create the main glossary:
+\item Create the main glossary (all on one line):
\begin{prompt}
makeindex -s sampleNtn.ist -t sampleNtn.glg -o sampleNtn.gls sampleNtn.glo
\end{prompt}
-\item Create the secondary glossary:
+\item Create the secondary glossary (all on one line):
\begin{prompt}
makeindex -s sampleNtn.ist -t sampleNtn.nlg -o sampleNtn.not sampleNtn.ntn
\end{prompt}
\end{enumerate}
-\item[sample.tex]\label{ex:sample} This document illustrates some of
+\exitem{} 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 and it also uses \ics{glsrefentry}, so an extra \LaTeX\
@@ -627,11 +695,11 @@ that this will only have an effect if you use
you will need to use the \texttt{-l} switch to indicate letter
ordering.)
-\item[sample-inline.tex]\label{ex:sample-inline} This document is
+\exitem{-inline} This document is
like \texttt{sample.tex}, above, but uses the \glostyle{inline}
glossary style to put the glossary in a footnote.
-\item[sampletree.tex]\label{ex:sampletree} This document illustrates
+\exitem{tree} This document illustrates
a hierarchical glossary structure where child entries have different
names to their corresponding parent entry. To create the document
do:
@@ -641,7 +709,7 @@ makeglossaries sampletree
latex sampletree
\end{prompt}
-\item[sample-dual.tex]\label{ex:sample-dual} This document
+\exitem{-dual} This document
illustrates how to define an entry that both appears in the list of
acronyms and in the main glossary. To create the document do:
\begin{prompt}
@@ -650,7 +718,7 @@ makeglossaries sample-dual
latex sample-dual
\end{prompt}
-\item[sample-langdict]\label{ex:sample-langdict} This document
+\exitem{-langdict} This document
illustrates how to use the glossaries package to create English
to French and French to English dictionaries. To create the document
do:
@@ -660,7 +728,7 @@ makeglossaries sample-langdict
latex sample-langdict
\end{prompt}
-\item[samplexdy.tex]\label{ex:samplexdy} This document illustrates
+\exitem{xdy} This document illustrates
how to use the \styfmt{glossaries} package with \gls{xindy} instead
of \gls{makeindex}. The document uses UTF8 encoding (with the
\sty{inputenc} package). The encoding is picked up by
@@ -702,7 +770,7 @@ otherwise, if you are using \texttt{samplexdy-mc.xdy}, then do
xindy -I xindy -M samplexdy-mc -t samplexdy.glg -o samplexdy.gls samplexdy.glo
\end{prompt}
-\item[samplexdy2.tex]\label{ex:samplexdy2} This document illustrates
+\exitem{xdy2} This document illustrates
how to use the \styfmt{glossaries} package where the location
numbers don't follow a standard format. This example will only work
with \gls{xindy}. To create the document do:
@@ -711,13 +779,14 @@ pdflatex samplexdy2
makeglossaries samplexdy2
pdflatex samplexdy2
\end{prompt}
-If you can't use \gls{makeglossaries} then you need to do:
+If you can't use \gls{makeglossaries} then you need to do (all on
+one line):
\begin{prompt}
xindy -L english -C utf8 -I xindy -M samplexdy2 -t samplexdy2.glg -o samplexdy2.gls samplexdy2.glo
\end{prompt}
See \sectionref{sec:xindyloc} for further details.
-\item[sampleutf8.tex]\label{ex:sampleutf8} This is another example
+\exitem{utf8} This is another example
that uses \gls{xindy}. Unlike \gls{makeindex},
\gls{xindy} can cope with accented or non-Latin characters. This
document uses UTF8 encoding. To create the document do:
@@ -749,14 +818,75 @@ follows (no line breaks):
makeindex -s sampleutf8.ist -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo
\end{prompt}
-\item[sampleaccsupp.tex]\label{ex:sampleaccsupp} This document
+\exitem{-index} This document uses
+the \styfmt{glossaries} package to create both a glossary and an
+index. This requires two \gls{makeglossaries} calls to ensure the
+document is up to date:
+\begin{prompt}
+latex sample-index
+makeglossaries sample-index
+latex sample-index
+makeglossaries sample-index
+latex sample-index
+\end{prompt}
+
+\exitem{-newkeys} This document illustrates how add custom keys.
+
+\exitem{-numberlist} This document illustrates how to reference the
+\gls{numberlist} in the document text. This requires an additional
+\LaTeX\ run:
+\begin{prompt}
+latex sample-numberlist
+makeglossaries sample-numberlist
+latex sample-numberlist
+latex sample-numberlist
+\end{prompt}
+
+\exitem{People} This document illustrates how you can hook into the
+standard sort mechanism to adjust the way the sort key is set. This
+requires an additional run to ensure the table of contents is
+up-to-date:
+\begin{prompt}
+latex samplePeople
+makeglossaries samplePeople
+latex samplePeople
+latex samplePeople
+\end{prompt}
+
+\exitem{Sort} This is another document that illustrates how to hook
+into the standard sort mechanism. An additional run is required to
+ensure the table of contents is up-to-date:
+\begin{prompt}
+latex sampleSort
+makeglossaries sampleSort
+latex sampleSort
+latex sampleSort
+\end{prompt}
+
+\exitem{-nomathhyper} This document illustrates how to selective
+enable and disable entry hyperlinks in \ics{glsentryfmt}.
+
+\exitem{-entryfmt} This document illustrates how to change the
+way an entry is displayed in the text.
+
+\exitem{-prefix} This document illustrates the use of the
+\sty{glossaries-prefix} package. An additional run is required to
+ensure the table of contents is up-to-date:
+\begin{prompt}
+latex sample-prefix
+makeglossaries sample-prefix
+latex sample-prefix
+latex sample-prefix
+\end{prompt}
+
+\exitem{accsupp} This document
uses the experimental \sty{glossaries-accsupp} package. The
symbol is set to the replacement text. Note that some PDF
viewers don't use the accessibility support. Information
about the \styfmt{glossaries-accsupp} package can be found in
\sectionref{sec:accsupp}.
-\end{description}
+\end{samplelist}
\section{Multi-Lingual Support}
@@ -781,10 +911,9 @@ If you want to use \gls*{xindy}, remember to use the
\begin{important}
Note that although an accented character, such as é, looks like a plain
character in your tex file, it's actually a macro and can therefore
-cause problems.
+cause expansion problems. You may need to switch off the field
+expansions with \cs{glsnoexpandfields}.
-\begin{enumerate}
-\item
If you use an accented (or other expandable) character at the start of
an entry name, you must place it in a group, or it will cause
a problem for commands that convert the first letter to uppercase
@@ -793,15 +922,6 @@ a problem for commands that convert the first letter to uppercase
\newglossaryentry{elite}{name={{é}lite},
description={select group or class}}
\end{verbatim}
-
-\item If you use an accented (or other expandable) character in an
-entry name and you haven't switched off the \gloskey{name} key
-\glsation{sanitize}, you must use commands like
-\ics{glsentrytext} or \ics{glstext} instead of \ics{glsentryname} or
-\ics{glsname} or you will end up with strange looking characters in
-your document.
-
-\end{enumerate}
\end{important}
If you use the \sty{inputenc} package, \gls{makeglossaries}
@@ -820,7 +940,9 @@ me the relevant translations either via email or via
However you must load \sty{babel} or \sty{polyglossia} \emph{before}
\styfmt{glossaries} to enable this. Note that if \sty{babel} is loaded
and the \sty{translator} package is detected on \TeX's path, then the
-\sty{translator} package will be loaded automatically. However,
+\sty{translator} package will be loaded automatically, unless you
+use the \pkgopt[false]{translate} or \pkgopt[babel]{translate}
+package options. However,
it may not pick up on the required languages so, if the predefined
text is not translated, you may need to explicitly load the
\sty{translator} package with the required languages. For example:
@@ -912,13 +1034,12 @@ this option.
Due to the varied nature of glossaries, it's likely that the
predefined translations may not be appropriate. If you are using the
-\sty{babel} package and do not have the \sty{translator} package
-installed, you need to be familiar with the advice given in
+\sty{babel} package and the \sty{glossaries} package option \pkgopt[babel]{translate}, you need to be familiar with the advice given in
\urlref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}{changing
-the words babel uses}. If you have the \sty{translator} package
-installed, then you can provide your own dictionary with the
-necessary modifications (using \cs{deftranslation}) and load it
-using \cs{usedictionary}.
+the words babel uses}. If you are using the \sty{translator}
+package, then you can provide your own dictionary with the necessary
+modifications (using \cs{deftranslation}) and load it using
+\cs{usedictionary}.
\begin{important}
Note that the dictionaries are loaded at the beginning of the
@@ -953,33 +1074,17 @@ can be found by \TeX.) If you want to share your custom dictionary,
you can upload it to \href{http://www.ctan.org/}{CTAN}.
If you are using \sty{babel} and don't want to use the
-\sty{translator} interface, you can suppress it using the package
-option \pkgopt[false]{translate}, and either load
-\sty{glossaries-babel} after \styfmt{glossaries} or specify you're own
-translations. For example:
+\sty{translator} interface, you can use the package
+option \pkgopt[babel]{translate}. For example:
\begin{verbatim}
\documentclass[british]{article}
\usepackage{babel}
-\usepackage[translate=false]{glossaries}
-\usepackage{glossaries-babel}
-\end{verbatim}
-or:
-\begin{verbatim}
-\documentclass[british]{article}
-
-\usepackage{babel}
-\usepackage[translate=false]{glossaries}
+\usepackage[translate=babel]{glossaries}
\addto\captionsbritish{%
\renewcommand*{\glossaryname}{List of Terms}%
\renewcommand*{\acronymname}{List of Acronyms}%
- \renewcommand*{\entryname}{Notation}%
- \renewcommand*{\descriptionname}{Description}%
- \renewcommand*{\symbolname}{Symbol}%
- \renewcommand*{\pagelistname}{Page List}%
- \renewcommand*{\glssymbolsgroupname}{Symbols}%
- \renewcommand*{\glsnumbersgroupname}{Numbers}%
}
\end{verbatim}
@@ -996,7 +1101,7 @@ details.
\section{Generating the Associated Glossary Files}
\label{sec:makeglossaries}
-In order to generate a sorted glossary with compact \glspl{locationlist},
+In order to generate a sorted glossary with compact \glspl{numberlist},
it is necessary to use an external \gls{indexingapp} as an
intermediate step. It is this application that creates the file
containing the code that typesets the glossary. If this step is
@@ -1011,6 +1116,14 @@ recommended if you're not writing in English. Commands that only
have an effect when \gls*{xindy} is used are described in
\sectionref{sec:xindy}.
+\begin{important}
+This is a multi-stage process, but there are methods of automating
+document compilation using applications such as \app{latexmk} and
+\app{arara}. See
+\url{http://www.dickimaw-books.com/latex/thesis/html/build.html} for
+more information.
+\end{important}
+
The \styfmt{glossaries} package comes with the Perl script
\gls{makeglossaries} which will run \gls{makeindex} or \gls{xindy}
on all the glossary files using a customized style file (which is
@@ -1106,7 +1219,11 @@ Community's} Know How section
describes how to do this for TeXnicCenter, and the thread
\href{http://groups.google.com/group/comp.text.tex/browse_thread/thread/edd83831b81b0759?hl=en}{\qt{Executing Glossaries' makeindex from a WinEdt
macro}} on the \texttt{comp.text.tex} newsgroup
-describes how to do it for WinEdt. For other editors see the editor's
+describes how to do it for WinEdt. \href{http://www.dickimaw-books.com/latex/thesis/html/build.html}{Section
+1.1 (Building Your Document)}
+of \urlfootref{http://www.dickimaw-books.com/latex/thesis/}{\qt{Using \LaTeX\ to Write a PhD Thesis}} describes how to do it
+for TeXWorks.
+For other editors see the editor's
user manual for further details.
If any problems occur, remember to check the transcript files
@@ -1155,13 +1272,20 @@ perl makeglossaries myDoc
\end{prompt}
There is a batch file called \texttt{makeglossaries.bat} which does
this for Windows users, but you must have Perl installed to be able
-to use it. You can specify in which directory the \filetype{.aux},
+to use it.\footnote{Apparently MiKTeX has an alternative
+\texttt{makeglossaries.exe} but I don't know how using this differs
+from using \texttt{makeglossaries.bat}.} You can specify in which directory the \filetype{.aux},
\filetype{.glo} etc files are located using the \texttt{-d} switch.
For example:
\begin{prompt}
pdflatex -output-directory myTmpDir myDoc
makeglossaries -d myTmpDir myDoc
\end{prompt}
+Note that \gls*{makeglossaries} assumes by default that
+\gls*{makeindex}\slash\gls*{xindy} is on your operating system's
+path. If this isn't the case, you can specify the full pathname
+using \texttt{-m} \meta{path/to/makeindex} for \gls*{makeindex}
+or \texttt{-x} \meta{path/to/xindy} for \gls*{xindy}.
The \gls{makeglossaries} script contains POD (Plain Old
Documentation). If you want, you can create a man page for
@@ -1173,18 +1297,17 @@ resulting file onto the man path. Alternatively do
\begin{important}
When upgrading the \styfmt{glossaries} package, make sure you also
upgrade your version of \gls{makeglossaries}. The current version is
-2.07.
+2.09.
\end{important}
\subsection{Using xindy explicitly}
\label{sec:xindyapp}
\Gls{xindy} comes with TeXLive, but not with MiKTeX. However MikTeX
-users can install it. There is
-\href{http://www.latex-community.org/forum/viewtopic.php?f=51&t=5383}{a
-thread} in the Makeindex section of the
-\urlfootref{http://www.latex-community.org/}{\LaTeX\ Community} that
-describes how to do this.
+users can install it. See
+\href{http://tex.stackexchange.com/questions/71167/how-to-use-xindy-with-miktex}{How
+to use Xindy with MikTeX} on
+\urlfootref{http://www.stackexchange.com/}{\TeX\ on StackExchange}.
If you want to use \gls{xindy} to process the glossary
files, you must make sure you have used the
@@ -1193,8 +1316,8 @@ files, you must make sure you have used the
\usepackage[xindy]{glossaries}
\end{verbatim}
This is required regardless of whether you use \gls{xindy}
-explicitly or whether it's called implicitly via
-\gls{makeglossaries} or \gls{makeglossariesgui}. This causes the glossary
+explicitly or whether it's called implicitly via applications such
+as \gls{makeglossaries} or \gls{makeglossariesgui}. This causes the glossary
entries to be written in raw \gls*{xindy} format, so you need to
use \texttt{-I xindy} \emph{not} \texttt{-I tex}.
@@ -1354,7 +1477,18 @@ if \gls{makeindex} should be used.
\chapter{Package Options}
\label{sec:pkgopts}
-This section describes the available \styfmt{glossaries} package options.
+This section describes the available \styfmt{glossaries} package
+options. You may omit the \texttt{=true} for boolean options. (For
+example, \pkgopt{acronym} is equivalent to \pkgopt[true]{acronym}).
+
+\begin{important}
+Note that \meta{key}=\meta{value} options can't be passed via the
+document class options. (This includes options where the
+\meta{value} part may be omitted, such as \pkgopt{acronym}.) This is
+a general limitation not restricted to the \styfmt{glossaries}
+package. Options that aren't \meta{key}=\meta{value} (such as
+\pkgopt{makeindex}) may be passed via the document class options.
+\end{important}
\section{General Options}
\label{sec:pkgopts-general}
@@ -1364,47 +1498,53 @@ This section describes the available \styfmt{glossaries} package options.
the \styfmt{glossaries} package.
\item[\pkgopt{nomain}] This suppresses the creation of the main
-glossary. Note that if you use this option, you must create another
-glossary in which to put all your entries (either via the
-\pkgopt{acronym} package option described in
-\sectionref{sec:pkgopts-acronym} or via \ics{newglossary} described
-in \sectionref{sec:newglossary}).
-
-\item[\pkgopt{sanitize}] This is a
-\meta{key}=\meta{value} option whose value is also a
-\meta{key}=\meta{value} list. By default, the \styfmt{glossaries}
-package \glspl{sanitize} the values of the \gloskey{name},
-\gloskey{description}, \gloskey{symbol} and \gloskey{sort} keys used when defining a
-new glossary entry. This means that you can use fragile commands in
-those keys, but it may lead to unexpected results if you try to
-display these values within the document text. This sanitization can
-be switched off using the \pkgopt{sanitize} package option.
-For example, to switch off the sanitization
-for the \gloskey{description} and \gloskey{name} keys, but not for
-the \gloskey{symbol} key, do:
-\begin{verbatim}
-\usepackage[sanitize={name=false,description=false,%
-symbol=true}]{glossaries}
-\end{verbatim}
-You can use \pkgopt[none]{sanitize} as a shortcut for\newline
-\pkgoptfmt{sanitize=\{name=false,description=false,symbol=false\}}.
-Note that this shortcut doesn't change the \gloskey{sort}
-sanitization. That one needs to be switched off explicitly:
-\begin{verbatim}
-\usepackage[sanitize=none,sanitize={sort=false}]{glossaries}
-\end{verbatim}
+glossary and associated \texttt{.glo} file, if unrequired. Note that
+if you use this option, you must create another glossary in which to
+put all your entries (either via the \pkgopt{acronym} (or
+\pkgopt{acronyms}) package option described in
+\sectionref{sec:pkgopts-acronym} or via the \pkgopt{symbols} or
+\pkgopt{numbers} options described in \sectionref{sec:pkgopts-other}
+or via \ics{newglossary} described in \sectionref{sec:newglossary}).
-\begin{important}%
-\textbf{Note}: this sanitization only applies to the \gloskey{name},
-\gloskey{description}, \gloskey{symbol} and \gloskey{sort} keys. It doesn't apply
-to any of the other keys so fragile commands contained in the value of
-the other keys must always be protected using \cs{protect}.
-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.
+\begin{important}
+If you don't use the main glossary and you don't use this option,
+\gls{makeglossaries} will produce the following warning:
+\begin{alltt}
+Warning: File '\emph{filename}.glo' is empty.
+Have you used any entries defined in glossary
+'main'?
+Remember to use package option 'nomain' if
+you don't want to use the main glossary.
+\end{alltt}
+If you did actually want to use the main glossary and you see this
+warning, check that you have referenced the entries in that glossary
+via commands such as \ics{gls}.
\end{important}
-\item[\pkgopt{savewrites}] This is a boolean option to minimises the
+\item[\pkgopt{sanitizesort}] This is a boolean option that
+determines whether or not to \gls{sanitize} the sort value when
+writing to the external glossary file. For example, suppose you
+define an entry as follows:
+\begin{verbatim}
+\newglossaryentry{hash}{name={\#},sort={#},
+ description={hash symbol}}
+\end{verbatim}
+The sort value (\verb|#|) must be sanitized before writing it to the
+glossary file, otherwise \LaTeX\ will try to interpret it as a
+parameter reference. If, on the other hand, you want the sort value
+expanded, you need to switch off the sanitization. For example,
+suppose you do:
+\begin{verbatim}
+\newcommand{\mysortvalue}{AAA}
+\newglossaryentry{sample}{name={sample},sort={\mysortvalue},
+ description={an example}}
+\end{verbatim}
+and you actually want \cs{mysortvalue} expanded, so that the entry
+is sorted according to \texttt{AAA}, then use the package option
+\pkgopt[false]{sanitizesort}. (The default is
+\pkgopt[true]{sanitizesort}.)
+
+\item[\pkgopt{savewrites}] This is a boolean option to minimise the
number of write registers used by the \styfmt{glossaries} package.
(Default is \pkgopt[false]{savewrites}.) There are only a limited
number of write registers, and if you have a large number of
@@ -1436,10 +1576,7 @@ document to avoid rewriting the files. For example:
\end{verbatim}
\end{important}
-\item[\pkgopt{translate}] This is a boolean option. The default is
-\pkgoptval{true}{translate} if \sty{babel}, \sty{polyglossia} or
-\sty{translator} have been loaded, otherwise the default value is
-\pkgoptval{false}{translate}.
+\item[\pkgopt{translate}] This can take the following values:
\begin{description}
\item[{\pkgopt[true]{translate}}] If \sty{babel} has been loaded
@@ -1455,18 +1592,52 @@ document to avoid rewriting the files. For example:
will be loaded.
\item[{\pkgopt[false]{translate}}] Don't provide translations, even
- if \sty{babel} or \sty{polyglossia} has been loaded. You can
- then provide you're own translations or explicitly load
- \sty{glossaries-babel} or \sty{glossaries-polyglossia}.
+ if \sty{babel} or \sty{polyglossia} has been loaded.
+ (Note that \sty{babel} provides the command \ics{glossaryname}
+ so that will still be translated if you have loaded \sty{babel}.)
+
+ \item[{\pkgopt[babel]{translate}}] Don't load the \sty{translator}
+package. Instead load \sty{glossaries-babel}.
+
+\begin{important}
+I recommend you use \pkgopt[babel]{translate} if you have any
+problems with the translations or with PDF bookmarks, but to maintain backward
+compatibility, if \sty{babel} has been loaded the default is
+\pkgopt[true]{translate}.
+\end{important}
+
\end{description}
+ If \pkgopt{translate} is specified without a value,
+ \pkgopt[true]{translate} is assumed. If \pkgopt{translate} isn't
+specified, \pkgopt[true]{translate} is assumed if \sty{babel},
+\sty{polyglossia} or \sty{translator} have been loaded. Otherwise
+\pkgopt[false]{translate} is assumed.
+
See \sectionref{sec:fixednames} for further details.
+\item[\pkgopt{notranslate}] This is equivalent to
+\pkgopt[false]{translate} and may be passed via the document class
+options.
+
\item[\pkgopt{hyperfirst}] This is a boolean option that specifies
whether each term has a hyperlink on \firstuse. The default is
\pkgopt[true]{hyperfirst} (terms on \gls{firstuse} have a hyperlink,
unless explicitly suppressed using starred versions of commands
-such as \ics{gls*}).
+such as \ics{gls*}). Note that this applies to all glossary types.
+It may be that you only want to apply this to just the acronyms
+(where the first use explains the meaning of the acronym) but not
+for ordinary glossary entries (where the first use is identical to
+subsequent uses). In this case, you can use \pkgopt[false]{hyperfirst} and
+apply \cs{glsunsetall} to all the regular (non-acronym) glossaries.
+For example:
+\begin{verbatim}
+\usepackage[acronym,hyperfirst=false]{glossaries}
+% acronym and glossary entry definitions
+
+% at the end of the preamble
+\glsunsetall[main]
+\end{verbatim}
\item[\pkgopt{nohypertypes}] Use this option if you have multiple
glossaries and you want to suppress the entry hyperlinks for a
@@ -1479,7 +1650,11 @@ value in braces if it contains any commas. Example:
\newglossary[nlg]{notation}{not}{ntn}{Notation}
\end{verbatim}
The values must be fully expanded, so \textbf{don't} try
-\verb|nohypertypes=\acronymtype|.
+\texttt{nohypertypes\discretionary{}{}{}=\ics{acronymtype}}. You may also use
+\begin{definition}
+\ics{GlsDeclareNoHyperList}\marg{list}
+\end{definition}
+instead or additionally.
See \sectionref{sec:glslink} for further details.
\item[\pkgopt{savenumberlist}] This is a boolean option that
@@ -1537,32 +1712,55 @@ You can change this value later in the document using
where \meta{name} is the sectional unit.
The start of each glossary adds information to the page header via
-\begin{definition}[\DescribeMacro{\glossarymark}]
-\cs{glossarymark}\marg{glossary title}
+\begin{definition}[\DescribeMacro{\glsglossarymark}]
+\cs{glsglossarymark}\marg{glossary title}
\end{definition}
-This defaults to \cs{@mkboth} unless \cls{memoir} is loaded, but you may
+This defaults to \cs{@mkboth}, but you may
need to redefine it.
For example, to only change the right header:
\begin{verbatim}
-\renewcommand{\glossarymark}[1]{\markright{#1}}
+\renewcommand{\glsglossarymark}[1]{\markright{#1}}
\end{verbatim}
or to prevent it from changing the headers:
\begin{verbatim}
-\renewcommand{\glossarymark}[1]{}
+\renewcommand{\glsglossarymark}[1]{}
\end{verbatim}
-If you want \cs{glossarymark} to use \cs{MakeUppercase} in the header, use the
+If you want \cs{glsglossarymark} to use \cs{MakeUppercase} in the header, use the
\pkgopt{ucmark} option described below.
Occasionally you may find that another package defines
\linebreak\cs{cleardoublepage} when it is not required. This may cause an
unwanted blank page to appear before each glossary. This can
-be fixed by redefining \ics{glsclearpage}:
+be fixed by redefining \DescribeMacro\glsclearpage\cs{glsclearpage}:
\begin{verbatim}
\renewcommand*{\glsclearpage}{\clearpage}
\end{verbatim}
-\item[\pkgopt{ucmark}] This is a boolean option (default: \pkgopt[false]{ucmark}). If
-set, \ics{glossarymark} is defined to use \ics{MakeUppercase}.
+\item[\pkgopt{ucmark}] This is a boolean option (default:
+\pkgopt[false]{ucmark}, unless \cls{memoir} has been loaded, in
+which case it defaults to \pkgopt[true]{ucmark}). If
+set, \ics{glsglossarymark} uses
+\ics{MakeTextUppercase}\footnote{Actually it uses
+\ics{mfirstucMakeUppercase} which is set to \sty{textcase}'s \cs{MakeTextUppercase}
+by the
+\styfmt{glossaries} package. This makes it consistent with
+\ics{makefirstuc}. (The \sty{textcase} package is automatically
+loaded by \styfmt{glossaries}.)}.
+You can test whether this option has been set or not using
+\begin{definition}[\DescribeMacro\ifglsucmark]
+\cs{ifglsucmark} \meta{true part}\cs{else} \meta{false part}\cs{fi}
+\end{definition}
+For example:
+\begin{verbatim}
+\renewcommand{\glsglossarymark}[1]{%
+ \ifglsucmark
+ \markright{\MakeTextUppercase{#1}}%
+ \else
+ \markright{#1}%
+ \fi}
+\end{verbatim}
+If \cls{memoir} has been loaded and \pkgopt{ucfirst} is set, then
+\cls{memoir}'s \ics{memUChead} is used.
\item[\pkgopt{numberedsection}]
The glossaries are placed in unnumbered sectional units by default,
@@ -1651,22 +1849,27 @@ option will automatically set \pkgopt[true]{entrycounter} and the
\ctr{glossaryentry} counter will be reset every time \meta{value} is
incremented.
-\DescribeMacro{\glsresetentrycounter}
+
\begin{important}
The \ctr{glossaryentry} counter isn't automatically reset at the
start of each glossary, except when glossary section numbering is on
and the counter used by \pkgopt{counterwithin} is the same as the
-counter used in the glossary's sectioning command. If you want the
-counter reset at the start of each glossary, you can redefine
-\ics{glossarypreamble} to use \cs{glsresetentrycounter}, which sets
-\ctr{glossaryentry} to zero:
+counter used in the glossary's sectioning command.
+\end{important}
+
+If you want the counter reset at the start of each glossary, you can
+redefine \ics{glossarypreamble} to use
+\begin{definition}[\DescribeMacro{\glsresetentrycounter}]
+\cs{glsresetentrycounter}
+\end{definition}
+which sets \ctr{glossaryentry} to zero:
\begin{verbatim}
\renewcommand{\glossarypreamble}{%
\glsresetentrycounter
}
\end{verbatim}
-or if you want a different preamble per glossary, use
-\ics{setglossarypreamble}. For example:
+or if you are using \ics{setglossarypreamble}, add it to each
+glossary preamble, as required. For example:
\begin{verbatim}
\setglossarypreamble[acronym]{%
\glsresetentrycounter
@@ -1677,7 +1880,6 @@ or if you want a different preamble per glossary, use
The preamble text here for the main glossary.
}
\end{verbatim}
-\end{important}
\item[\pkgopt{subentrycounter}] This is a boolean option. (Default
is \pkgopt[false]{subentrycounter}.) If set, each level~1
@@ -1694,28 +1896,35 @@ associated with the sub-entry.
(Default is \pkgopt[list]{style}.) Its value should be the name of
the glossary style to use. This key may only be used for styles
defined in \sty{glossary-list}, \sty{glossary-long},
-\sty{glossary-super} or \sty{glossary-tree}. (See
-\sectionref{sec:styles}.)
+\sty{glossary-super} or \sty{glossary-tree}. Alternatively, you can
+set the style using
+\begin{definition}
+\cs{setglossarystyle}\marg{style name}
+\end{definition}
+(See \sectionref{sec:styles} for further details.)
\item[\pkgopt{nolong}] This prevents the \styfmt{glossaries} package
from automatically loading \sty{glossary-long} (which means that
the \sty{longtable} package also won't be loaded). This reduces
overhead by not defining unwanted styles and commands. Note that if
you use this option, you won't be able to use any of the
-glossary styles defined in the \styfmt{glossary-long} package.
+glossary styles defined in the \styfmt{glossary-long} package (unless
+you explicitly load \sty{glossary-long}).
\item[\pkgopt{nosuper}] This prevents the \styfmt{glossaries} package
from automatically loading \sty{glossary-super} (which means that
the \sty{supertabular} package also won't be loaded). This reduces
overhead by not defining unwanted styles and commands. Note that if
you use this option, you won't be able to use any of the
-glossary styles defined in the \styfmt{glossary-super} package.
+glossary styles defined in the \styfmt{glossary-super} package
+(unless you explicitly load \sty{glossary-super}).
\item[\pkgopt{nolist}] This prevents the \styfmt{glossaries} package
from automatically loading \sty{glossary-list}. This reduces
overhead by not defining unwanted styles. Note that if
you use this option, you won't be able to use any of the
-glossary styles defined in the \styfmt{glossary-list} package.
+glossary styles defined in the \styfmt{glossary-list} package
+(unless you explicitly load \sty{glossary-list}).
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.
@@ -1724,19 +1933,20 @@ something else.
from automatically loading \sty{glossary-tree}. This reduces
overhead by not defining unwanted styles. Note that if
you use this option, you won't be able to use any of the
-glossary styles defined in the \styfmt{glossary-tree} package.
+glossary styles defined in the \styfmt{glossary-tree} package
+(unless you explicitly load \sty{glossary-tree}).
\item[\pkgopt{nostyles}] This prevents all the predefined styles
from being loaded. If you use this option, you need to load a
glossary style package (such as \sty{glossary-mcols}). Also 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
+Instead you must either use \ics{setglossarystyle}\marg{style} or the
\gloskey[printglossary]{style} key in the optional argument to
\ics{printglossary}. Example:
\begin{verbatim}
\usepackage[nostyles]{glossaries}
\usepackage{glossary-mcols}
-\glossarystyle{mcoltree}
+\setglossarystyle{mcoltree}
\end{verbatim}
\item[\pkgopt{nonumberlist}] This option will suppress the
@@ -1791,9 +2001,133 @@ which they were defined (the \gloskey{sort} key in
\item \pkgoptval{use}{sort} : entries are sorted according to the
order in which they are used in the document (the \gloskey{sort} key
in \cs{newglossaryentry} is ignored).
+
+Both \pkgopt[def]{sort} and \pkgopt[use]{sort} set the sort key to a
+six digit number via
+\begin{definition}[\DescribeMacro\glssortnumberfmt]
+\cs{glssortnumberfmt}\marg{number}
+\end{definition}
+(padded with leading zeros, where necessary). This can be
+redefined, if required, before the entries are defined (in the
+case of \pkgopt[def]{sort}) or before the entries are used
+(in the case of \pkgopt[use]{sort}).
\end{itemize}
-The default is \pkgopt[standard]{sort}.
+The default is \pkgopt[standard]{sort}. When the standard sort
+option is in use, you can hook into the sort mechanism by
+redefining:
+\begin{definition}[\DescribeMacro{\glsprestandardsort}]
+\cs{glsprestandardsort}\marg{sort cs}\marg{type}\marg{label}
+\end{definition}
+where \meta{sort cs} is a temporary control sequence that stores the
+sort value (which was either explicitly set via the \gloskey{sort}
+key or implicitly set via the \gloskey{name} key) before any escaping of the
+\gls{makeindex}\slash\gls{xindy} special characters is performed.
+By default \cs{glsprestandardsort} just does:
+\begin{definition}[\DescribeMacro{\glsdosanitizesort}]
+\cs{glsdosanitizesort}
+\end{definition}
+which sanitizes \meta{sort cs} if the \pkgopt{sanitizesort} package option
+is set (or does nothing if the package option \pkgopt[false]{sanitizesort} is used).
+
+The other arguments, \meta{type} and \meta{label}, are the
+glossary type and the entry label for the current entry. Note that
+\meta{type} will always be a control sequence, but \meta{label} will
+be in the form used in the first argument of \ics{newglossaryentry}.
+
+\begin{important}
+Redefining \cs{glsprestandardsort} won't affect any entries that
+have already been defined and will have no effect at all if you
+are using \pkgopt[def]{sort} or \pkgopt[use]{sort}.
+\end{important}
+
+\begin{example}{Mixing Alphabetical and Order of Definition Sorting}{ex:diffsorts}
+Suppose I have three glossaries: \texttt{main},
+\texttt{acronym} and \texttt{notation}, and let's suppose
+I want the \texttt{main} and \texttt{acronym} glossaries to be
+sorted alphabetically, but the \texttt{notation} type should be
+sorted in order of definition. I can set the sort to standard
+(which is the default, but can be explicitly set via the
+package option \pkgopt[standard]{sort}), and I can either define
+all my \texttt{main} and \texttt{acronym} entries, then
+redefine \cs{glsprestandardsort} to set \meta{sort cs} to
+an incremented integer, and then define all my
+\texttt{notation} entries. Alternatively, I can redefine
+\cs{glsprestandardsort} to check for the glossary type and only
+modify \meta{sort cs} if \meta{type} is \texttt{notation}.
+
+The first option can be achieved as follows:
+\begin{verbatim}
+\newcounter{sortcount}
+
+\renewcommand{\glsprestandardsort}[3]{%
+ \stepcounter{sortcount}%
+ \edef#1{\glssortnumberfmt{\arabic{sortcount}}}%
+}
+\end{verbatim}
+The second option can be achieved as follows:
+\begin{verbatim}
+\newcounter{sortcount}
+
+\renewcommand{\glsprestandardsort}[3]{%
+ \ifdefstring{#2}{notation}%
+ {%
+ \stepcounter{sortcount}%
+ \edef#1{\glssortnumberfmt{\arabic{sortcount}}}%
+ }%
+ {%
+ \glsdosanitizesort
+ }%
+}
+\end{verbatim}
+(\cs{ifdefstring} is defined by the \sty{etoolbox} package.)
+For a complete document, see the sample file \samplefile{Sort}.
+\end{example}
+
+\begin{example}{Customizing Standard Sort}{ex:customsort}
+Suppose you want a glossary of people and you want the names listed
+as \meta{first-name} \meta{surname} in the glossary, but you want the names
+sorted by \meta{surname}, \meta{first-name}. You can do this by
+defining a command called, say,
+\cs{name}\marg{first-name}\marg{surname} that you can use in the
+\gloskey{name} key when you define the entry, but hook into the
+standard sort mechanism to temporarily redefine \cs{name} while the
+sort value is being set.
+
+First, define two commands to set the person's name:
+\begin{verbatim}
+\newcommand{\sortname}[2]{#2, #1}
+\newcommand{\textname}[2]{#1 #2}
+\end{verbatim}
+and \cs{name} needs to be initialised to \cs{textname}:
+\begin{verbatim}
+\let\name\textname
+\end{verbatim}
+Now redefine \cs{glsprestandardsort} so that it temporarily sets
+\cs{name} to \cs{sortname} and expands the sort value, then sets
+\cs{name} to \cs{textname} so that the person's name appears as
+\meta{first-name} \meta{surname} in the text:
+\begin{verbatim}
+\renewcommand{\glsprestandardsort}[3]{%
+ \let\name\sortname
+ \edef#1{\expandafter\expandonce\expandafter{#1}}%
+ \let\name\textname
+ \glsdosanitizesort
+}
+\end{verbatim}
+(The somewhat complicate use of \cs{expandafter} etc helps to
+protect fragile commands, but care is still needed.)
+
+Now the entries can be defined:
+\begin{verbatim}
+\newglossaryentry{joebloggs}{name={\name{Joe}{Bloggs}},
+ description={some information about Joe Bloggs}}
+
+\newglossaryentry{johnsmith}{name={\name{John}{Smith}},
+ description={some information about John Smith}}
+\end{verbatim}
+For a complete document, see the sample file \samplefile{People}.
+\end{example}
\item[\pkgopt{order}] This may take two values:
\pkgoptval{word}{order} or \pkgoptval{letter}{order}. The default
@@ -1819,7 +2153,7 @@ call \gls*{xindy}. If you don't use \gls*{makeglossaries}, you need to
remember to use \gls*{xindy} not \gls{makeindex}. The indexing style
file will been given a \filetype{.xdy} extension.
-The \pkgopt{xindy} package option may additionally have a value that
+This package option may additionally have a value that
is a \meta{key}=\meta{value} comma-separated list to override the
language and codepage. For example:
\begin{verbatim}
@@ -1830,8 +2164,17 @@ glossary. This defaults to true, but can be suppressed. For example:
\begin{verbatim}
\usepackage[xindy={glsnumbers=false}]{glossaries}
\end{verbatim}
-See \sectionref{sec:xindy} for further details on using \gls{xindy}
-with the \styfmt{glossaries} package.
+If no value is supplied to this package option (either simply
+writing \texttt{xindy} or writing \verb|xindy={}|) then the
+language, codepage and number group settings are unchanged. See
+\sectionref{sec:xindy} for further details on using \gls{xindy} with
+the \styfmt{glossaries} package.
+
+\item[\pkgopt{xindygloss}] This is equivalent to
+\verb|xindy={}| (that is, the \pkgopt{xindy} option without any value
+supplied) and may be used as a document class option. The language
+and code page can be set via \ics{GlsSetXdyLanguage} and
+\ics{GlsSetXdyCodePage} (see \sectionref{sec:langenc}.)
\end{description}
@@ -1844,16 +2187,36 @@ label \texttt{acronym}. This is equivalent to:
\begin{verbatim}
\newglossary[alg]{acronym}{acr}{acn}{\acronymname}
\end{verbatim}
+It will also define
+\begin{definition}[\DescribeMacro\printacronyms]
+\cs{printacronyms}\oarg{options}
+\end{definition}
+that's equivalent to
+\begin{alltt}
+\ics{printglossary}[type=acronym,\meta{options}]
+\end{alltt}
+(unless that command is already defined before the beginning of the
+document or the package option \pkgopt{compatible-3.07} is used).
+
If the \pkgopt{acronym} package option is used, \ics{acronymtype}
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} unless the \pkgopt{nomain} option has been used.}
Entries that are defined using \ics{newacronym} are placed in
the glossary whose label is given by \ics{acronymtype}, unless
another glossary is explicitly specified.
+\begin{important}
+Remember to use the \pkgopt{nomain} package option if you're only
+interested in using this \texttt{acronym} glossary.
+\end{important}
+
+\item[\pkgopt{acronyms}] This is equivalent to
+\pkgopt[true]{acronym} and may be used in the document class option
+list.
+
\item[\pkgopt{acronymlists}] By default, only the \cs{acronymtype}
glossary is considered to be a list of acronyms. If you have other
lists of acronyms, you can specify them as a comma-separated list
@@ -1869,39 +2232,138 @@ so you can add glossaries you haven't defined yet. For example:
\usepackage[acronym,acronymlists={main,acronym2}]{glossaries}
\newglossary[alg2]{acronym2}{acr2}{acn2}{Statistical Acronyms}
\end{verbatim}
+You can use
+\begin{definition}[\DescribeMacro\DeclareAcronymList]
+\cs{DeclareAcronymList}\marg{list}
+\end{definition}
+instead of or in addition to the \pkgopt{acronymlists} option.
+This will add the glossaries given in \meta{list} to the list of glossaries
+that are identified as lists of acronyms. To replace the list of acronym lists
+use with a new list use:
+\begin{definition}[\DescribeMacro\SetAcronymLists]
+\cs{SetAcronymLists}\marg{list}
+\end{definition}
-\item[\pkgopt{description}] This option changes the definition of
-\ics{newacronym} to allow a description. This option has no effect if
-you defined your own custom acronym style. See
-\sectionref{sec:acronyms} for further details.
+You can determine if a glossary has been identified as being a list
+of acronyms using:
+\begin{definition}[\DescribeMacro\glsIfListOfAcronyms]
+\cs{glsIfListOfAcronyms}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
-\item[\pkgopt{footnote}] This option changes the definition of
-\ics{newacronym} and the way that acronyms are displayed. This
-option has no effect if you defined your own custom acronym style. See
+\item[\pkgopt{description}] This option changes the definition of
+\ics{newacronym} to allow a description. This option may have no effect if
+you define your own custom acronym style. See
\sectionref{sec:acronyms} for further details.
\item[\pkgopt{smallcaps}] This option changes the definition of
\ics{newacronym} and the way that acronyms are displayed. This
-option may have no effect if you defined your own custom acronym
+option may have no effect if you define your own custom acronym
style. See \sectionref{sec:acronyms} for further details.
\item[\pkgopt{smaller}] This option changes the definition of
-\ics{newacronym} and the way that acronyms are displayed. If you use
-this option, you will need to include the \sty{relsize} package or
-otherwise define \ics{textsmaller} or redefine \ics{acronymfont}.
-This option may have no effect if you defined your own custom acronym
+\ics{newacronym} and the way that acronyms are displayed.
+\begin{important}
+If you use this option, you will need to include the \sty{relsize}
+package or otherwise define \ics{textsmaller} or redefine
+\ics{acronymfont}.
+\end{important}
+This option may have no effect if you define your own custom acronym
style. See \sectionref{sec:acronyms} for further details.
+\item[\pkgopt{footnote}] This option changes the definition of
+\ics{newacronym} and the way that acronyms are displayed. This
+option has no effect if you define your own custom acronym style. See
+\sectionref{sec:acronyms} for further details.
+
\item[\pkgopt{dua}] This option changes the definition of
\ics{newacronym} so that acronyms are always expanded. This
-option has no effect if you defined your own custom acronym style.
+option may have no effect if you define your own custom acronym style.
See \sectionref{sec:acronyms} for further details.
\item[\pkgopt{shortcuts}] This option provides shortcut commands
for acronyms. See \sectionref{sec:acronyms} for further details.
+Alternatively you can use:
+\begin{definition}[\DescribeMacro\DefineAcronymShortcuts]
+\cs{DefineAcronymShortcuts}
+\end{definition}
+
+\end{description}
+
+\section{Other Options}
+\label{sec:pkgopts-other}
+
+Other available options that don't fit any of the above categories
+are:
+\begin{description}
+\item[\pkgopt{symbols}] This option defines a new glossary type with
+the label \texttt{symbols} via
+\begin{verbatim}
+\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname}
+\end{verbatim}
+It also defines
+\begin{definition}[\DescribeMacro\printsymbols]
+\cs{printsymbols}\oarg{options}
+\end{definition}
+which is a synonym for
+\ics{printglossary}\texttt{[type=symbols,\meta{options}]}.
+
+\begin{important}
+Remember to use the \pkgopt{nomain} package option if you're only
+interested in using this \texttt{symbols} glossary.
+\end{important}
+
+\item[\pkgopt{numbers}] This option defines a new glossary type with
+the label \texttt{numbers} via
+\begin{verbatim}
+\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname}
+\end{verbatim}
+It also defines
+\begin{definition}[\DescribeMacro\printnumbers]
+\cs{printnumbers}\oarg{options}
+\end{definition}
+which is a synonym for
+\ics{printglossary}\texttt{[type=numbers,\meta{options}]}.
+
+\begin{important}
+Remember to use the \pkgopt{nomain} package option if you're only
+interested in using this \texttt{numbers} glossary.
+\end{important}
+
+\item[\pkgopt{compatible-2.07}] Compatibility mode for old documents
+created using version 2.07 or below.
+
+\item[\pkgopt{compatible-3.07}] Compatibility mode for old documents
+created using version 3.07 or below.
\end{description}
+\section{Setting Options After Package Loaded}
+
+Some of the options described above may also be set after the
+\sty{glossaries} package has been loaded using
+\begin{definition}[\DescribeMacro{\setupglossaries}]
+\cs{setupglossaries}\marg{key-val list}
+\end{definition}
+The following package options \textbf{can't} be used in
+\cs{setupglossaries}: \pkgopt{xindy}, \pkgopt{xindygloss}, \pkgopt{makeindex},
+\pkgopt{nolong}, \pkgopt{nosuper}, \pkgopt{nolist},
+\pkgopt{notree}, \pkgopt{nostyles}, \pkgopt{nomain},
+\pkgopt{compatible-2.07}, \pkgopt{translate}, \pkgopt{notranslate},
+\pkgopt{acronym}. These options have to be set while the package is
+loading, except for the \pkgopt{xindy} sub-options which can be set
+using commands like \ics{GlsSetXdyLanguage} (see
+\sectionref{sec:xindy} for further details).
+
+\begin{important}
+I recommend you use this command as soon as possible after loading
+\sty{glossaries} otherwise you might end up using it too late for
+the change to take effect. For example, if you try changing the
+acronym styles (such as \pkgopt{smallcaps}) after you have started
+defining your acronyms, you are likely to get unexpected results. If
+you try changing the sort option after you have started to define
+entries, you may get unexpected results.
+\end{important}
+
\chapter{Setting Up}
\label{sec:setup}
@@ -1912,8 +2374,8 @@ The command
must be placed in the preamble in order to create the customised
\gls{makeindex} (\filetype{.ist}) or \gls{xindy} (\filetype{.xdy})
style file and to ensure that glossary entries are written to the
-appropriate output files. If you omit \cs{makeglossaries} none of
-the glossaries will be created.
+appropriate output files. \textbf{If you omit \cs{makeglossaries} none of
+the glossaries will be created.}
\begin{important}
Note that some of the commands provided by the \styfmt{glossaries}
@@ -1987,7 +2449,9 @@ 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 \ics{newglossaryentry} and
\ics{newacronym} was removed in version 1.13, but the restriction
-remains for \ics{loadglsentries}.} However only those entries that
+remains for \ics{loadglsentries}. See \sectionref{sec:docdefs} for
+a discussion of the problems with defining entries within the
+document instead of in the preamble.} However only those entries that
occur in the document (using any of the commands described in
\sectionref{sec:glslink}, \sectionref{sec:glsadd} or
\sectionref{sec:crossref}) will appear in the glossary. Each time an
@@ -2007,10 +2471,47 @@ overwritten.} See
New glossary entries are defined using the command:
\begin{definition}[\DescribeMacro{\newglossaryentry}]
-\cs{newglossaryentry}\marg{label}\marg{key-val list}
+\cs{newglossaryentry}\marg{label}\marg{key=value list}
+\end{definition}
+This is a short command, so values in \meta{key-val list} can't
+contain any paragraph breaks. If you have a long description that
+needs to span multiple paragraphs, use
+\begin{definition}[\DescribeMacro{\longnewglossaryentry}]
+\cs{longnewglossaryentry}\marg{label}\marg{key=value
+list}\marg{long description}
+\end{definition}
+instead. Note that, unlike \cs{newglossaryentry}, the command
+\cs{longnewglossaryentry} may only be used in the preamble.
+Be careful of unwanted spaces. \cs{longnewglossaryentry}
+will remove trailing spaces in the description (via \cs{unskip})
+but won't remove leading spaces (otherwise it would interfere with
+commands like \cs{Glsentrydesc}).
+
+There are also commands that will only define the entry if it
+hasn't already been defined:
+\begin{definition}[\DescribeMacro\provideglossaryentry]
+\cs{provideglossaryentry}\marg{label}\marg{key=value list}
+\end{definition}
+and\par
+\DescribeMacro\longprovideglossaryentry
+\begin{definition}
+\cs{longprovideglossaryentry}\marg{label}\marg{key=value
+list}\marg{long description}
\end{definition}
-The first argument, \meta{label}, must be a unique label with which
-to identify this entry. The second argument, \meta{key-val list}, is
+(These are both preamble-only commands.)
+
+For all the above commands, the first argument, \meta{label}, must be
+a~unique label with which to identify this entry. This can't contain
+any non-expandable commands or active characters.
+
+\begin{important}
+Note that although an accented character or other non-Latin
+character, such as \'e or \th, looks like a plain character in your
+\texttt{.tex} file, it's actually a macro (an active character) and
+can therefore can't be used in the label.
+\end{important}
+
+The second argument, \meta{key=value list}, is
a \meta{key}=\meta{value} list that supplies the relevant
information about this entry. There are two required fields:
\gloskey{description} and either \gloskey{name} or \gloskey{parent}.
@@ -2034,6 +2535,7 @@ break in the description use
\begin{definition}[\DescribeMacro{\glspar}]
\cs{glspar}
\end{definition}
+or, better, use \cs{longnewglossaryentry}.
However, note that not all glossary styles support multi-line
descriptions. If you are using one of the tabular-like glossary
styles that permit multi-line descriptions, use \ics{newline}
@@ -2044,13 +2546,8 @@ the parent entry must be defined before its sub-entries.
See \sectionref{sec:subentries} for further details.
\item[{\gloskey{descriptionplural}}] The plural form of the
-description (as passed to \ics{glsdisplay} and \ics{glsdisplayfirst}
-by \ics{glspl}, \ics{Glspl} and \ics{GLSpl}). If omitted, the value
-is set to the same as the \gloskey{description} key. (Note that if
-you want the description to appear in the main body of the document,
-you must switch off the description \glsation{sanitize} using the
-\pkgopt{sanitize} package option described in
-\sectionref{sec:pkgopts-general}.)
+description, if required. If omitted, the value
+is set to the same as the \gloskey{description} key.
\item[{\gloskey{text}}] How this entry will appear in the document text
when using \ics{gls} (or one of its uppercase variants). If this
@@ -2088,10 +2585,6 @@ used the \gloskey{first} key.
\item[{\gloskey{symbol}}] This field is provided to allow the user
to specify an associated symbol. If omitted, the value is set to
\cs{relax}. Note that not all glossary styles display the symbol.
-(If you want the symbol to appear in the main body of the document,
-you must switch off the symbol \glsation{sanitize} using the
-\pkgopt{sanitize} package option described in
-\sectionref{sec:pkgopts-general}.)
\item[{\gloskey{symbolplural}}] This is the plural form of the
symbol (as passed to \ics{glsdisplay} and \ics{glsdisplayfirst}
@@ -2104,8 +2597,9 @@ by the \gloskey{name} field. In general, it's best to use the
\gloskey{sort} key if the \gloskey{name} contains commands (e.g.\
\verb|\ensuremath{\alpha}|). Note that the package options
\pkgopt[def]{sort} and \pkgopt[use]{sort} override the
-\gloskey{sort} key in \ics{newglossaryentry} (see
-\sectionref{sec:pkgopts-sort}).
+\gloskey{sort} key in \ics{newglossaryentry} and redefining
+\ics{glsprestandardsort} can also be used to override the
+\gloskey{sort} key (see \sectionref{sec:pkgopts-sort}).
\item[{\gloskey{type}}] This specifies the label of the glossary in
which this entry belongs. If omitted, the default glossary is
@@ -2115,11 +2609,15 @@ assumed unless \ics{newacronym} is used (see
\item[{\gloskey{user1}, \ldots, \gloskey{user6}%
\igloskey{user2}\igloskey{user3}\igloskey{user4}\igloskey{user5}}]
Six keys provided for any additional information the user may want
-to specify. (For example an associated dimension or an alternative
-plural or some other grammatical construct.)
+to specify. (For example, an associated dimension or an alternative
+plural or some other grammatical construct.) Alternatively, you can
+add new keys using \ics{glsaddkey} (see \sectionref{sec:addkey}).
+Other keys are also provided by the \sty{glossaries-prefix}
+(\sectionref{sec:prefix}) and \sty{glossaries-accsupp}
+(\sectionref{sec:accsupp}) packages.
\item[{\gloskey{nonumberlist}}] A boolean key. If the value is
-missing or is "true", this will suppress the \gls{numberlist} just for
+missing or is \texttt{true}, this will suppress the \gls{numberlist} just for
this entry. Conversely, if you have used the package option
\pkgopt{nonumberlist}, you can activate the \gls*{numberlist} just
for this entry with \gloskey{nonumberlist=false}.
@@ -2131,9 +2629,10 @@ glossary, but will not automatically add the cross-referenced entry.
The referenced entry should be supplied as the value to this key.
If you want to override the \qt{see} tag, you can supply the new
tag in square brackets before the label. For example
-\verb|see=[see also]{anotherlabel}|. Note that if you have
+\verb|see=[see also]{anotherlabel}|. \textbf{Note that if you have
suppressed the \gls{numberlist}, the cross-referencing information
-won't appear in the glossary. You can override this for individual
+won't appear in the glossary, as it forms part of the
+\gls*{numberlist}.} You can override this for individual
glossary entries using \gloskey{nonumberlist=false} (see above).
Alternatively, you can use the \pkgopt{seeautonumberlist} package
option. For further details, see \sectionref{sec:crossref}.
@@ -2147,9 +2646,13 @@ option. For further details, see \sectionref{sec:crossref}.
The following keys are reserved for \ics{newacronym} (see
\sectionref{sec:acronyms}): \gloskey{long}, \gloskey{longplural},
-\gloskey{short} and \gloskey{shortplural}.
+\gloskey{short} and \gloskey{shortplural}. Additional keys are
+provided by the \sty{glossaries-prefix} (\sectionref{sec:prefix})
+and the \sty{glossaries-accsupp} (\sectionref{sec:accsupp}) packages.
+You can also define your own custom keys (see
+\sectionref{sec:addkey}).
-Note that if the name starts with an accented letter or non-Roman
+Note that if the name starts with an accented letter or other non-Latin
character, you must group the character, otherwise it will
cause a problem for commands like \ics{Gls} and \ics{Glspl}.
For example:
@@ -2208,7 +2711,8 @@ define an easy to remember synonym. For example:
\let\glsaltpl\glsuseri
\end{verbatim}
Then you don't have to remember which key you used to store the
-alternative plural.
+second plural. Alternatively, you can define your own keys using
+\ics{glsaddkey}, described in \sectionref{sec:addkey}.
If you are using a language that usually forms plurals
by appending a different letter, or sequence of letters, you can
@@ -2254,6 +2758,157 @@ Jane \glsd{play} in the park yesterday.
Peter and Jane \glsd{run} in the park last week.
\end{verbatim}
+Alternatively, you can define your own keys using
+\ics{glsaddkey}, described below in \sectionref{sec:addkey}.
+
+\section{Additional Keys}
+\label{sec:addkey}
+
+You can now also define your own custom keys using:
+\begin{definition}[\DescribeMacro\glsaddkey]
+\cs{glsaddkey}\marg{key}%
+\marg{default value}%
+\marg{no link cs}%
+\marg{no link ucfirst cs}%
+\marg{link cs}%
+\marg{link ucfirst cs}%
+\marg{link allcaps cs}
+\end{definition}
+where:
+\begin{description}
+\item[\meta{key}] is the new key to use in \ics{newglossaryentry}
+(or similar commands such as \ics{longnewglossaryentry});
+\item[\meta{default value}] is the default value to use if this key
+isn't used in an entry definition (this may reference the current
+entry label via \cs{glslabel}, but you will have to switch on
+expansion via the starred version of \cs{glsaddkey});
+\item[\meta{no link cs}] is the control sequence to use analogous
+to commands like \ics{glsentrytext};
+\item[\meta{no link ucfirst cs}] is the control sequence to use analogous
+to commands like \ics{Glsentrytext};
+\item[\meta{link cs}] is the control sequence to use analogous
+to commands like \ics{glstext};
+\item[\meta{link ucfirst cs}] is the control sequence to use analogous
+to commands like \ics{Glstext};
+\item[\meta{link allcaps cs}] is the control sequence to use analogous
+to commands like \ics{GLStext}.
+\end{description}
+The starred version of \cs{glsaddkey} switches on expansion for this
+key. The unstarred version doesn't override the current expansion
+setting.
+
+\begin{example}{Defining Custom Keys}{ex:addkey}
+Suppose I want to define two new keys, \texttt{ed} and \texttt{ing},
+that default to the entry text followed by \qt{ed} and \qt{ing},
+respectively. The default value will need expanding in both cases, so
+I need to use the starred form:
+\begin{verbatim}
+ % Define "ed" key:
+ \glsaddkey*
+ {ed}% key
+ {\glsentrytext{\glslabel}ed}% default value
+ {\glsentryed}% command analogous to \glsentrytext
+ {\Glsentryed}% command analogous to \Glsentrytext
+ {\glsed}% command analogous to \glstext
+ {\Glsed}% command analogous to \Glstext
+ {\GLSed}% command analogous to \GLStext
+
+ % Define "ing" key:
+ \glsaddkey*
+ {ing}% key
+ {\glsentrytext{\glslabel}ing}% default value
+ {\glsentrying}% command analogous to \glsentrytext
+ {\Glsentrying}% command analogous to \Glsentrytext
+ {\glsing}% command analogous to \glstext
+ {\Glsing}% command analogous to \Glstext
+ {\GLSing}% command analogous to \GLStext
+\end{verbatim}
+Now I can define some entries:
+\begin{verbatim}
+ % No need to override defaults for this entry:
+
+ \newglossaryentry{jump}{name={jump},description={}}
+
+ % Need to override defaults on these entries:
+
+ \newglossaryentry{run}{name={run},%
+ ed={ran},%
+ ing={running},%
+ description={}}
+
+ \newglossaryentry{waddle}{name={waddle},%
+ ed={waddled},%
+ ing={waddling},%
+ description={}}
+\end{verbatim}
+
+These entries can later be used in the document:
+\begin{verbatim}
+The dog \glsed{jump} over the duck.
+
+The duck was \glsing{waddle} round the dog.
+
+The dog \glsed{run} away from the duck.
+\end{verbatim}
+For a complete document, see the sample file \samplefile{-newkeys}.
+\end{example}
+
+\section{Expansion}
+\label{sec:expansion}
+
+When you define new glossary entries expansion is performed by
+default, except for the \gloskey{name}, \gloskey{description},
+\gloskey{descriptionplural}, \gloskey{symbol}, \gloskey{symbolplural}
+and \gloskey{sort} keys (these keys all have expansion suppressed via
+\cs{glssetnoexpandfield}).
+
+You can switch expansion on or off for individual keys using
+\begin{definition}[\DescribeMacro\glssetexpandfield]
+\cs{glssetexpandfield}\marg{field}
+\end{definition}
+or
+\begin{definition}[\DescribeMacro\glssetnoexpandfield]
+\cs{glssetnoexpandfield}\marg{field}
+\end{definition}
+respectively, where \meta{field} is the field tag corresponding to
+the key. In most cases, this is the same as the name of the key
+except for those listed in \tableref{tab:fieldmap}.
+
+\begin{table}[htbp]
+\caption{Key to Field Mappings}
+\label{tab:fieldmap}
+\centering
+\begin{tabular}{ll}
+\bfseries Key & \bfseries Field\\
+\gloskey{sort} & \ttfamily sortvalue\\
+\gloskey{firstplural} & \ttfamily firstpl\\
+\gloskey{description} & \ttfamily desc\\
+\gloskey{descriptionplural} & \ttfamily descplural\\
+\gloskey{user1} & \ttfamily useri\\
+\gloskey{user2} & \ttfamily userii\\
+\gloskey{user3} & \ttfamily useriii\\
+\gloskey{user4} & \ttfamily useriv\\
+\gloskey{user5} & \ttfamily userv\\
+\gloskey{user6} & \ttfamily uservi\\
+\gloskey{longplural} & \ttfamily longpl\\
+\gloskey{shortplural} & \ttfamily shortpl
+\end{tabular}
+\end{table}
+
+Any keys that haven't had the expansion explicitly set using
+\cs{glssetexpandfield} or \cs{glssetnoexpandfield} are governed by
+\begin{definition}[\DescribeMacro\glsexpandfields]
+\cs{glsexpandfields}
+\end{definition}
+and
+\begin{definition}[\DescribeMacro\glsnoexpandfields]
+\cs{glsnoexpandfields}
+\end{definition}
+
+If your entries contain any fragile commands, I recommend you switch
+off expansion via \cs{glsnoexpandfields}. (This should be used
+before you define the entries.)
+
\section{Sub-Entries}
\label{sec:subentries}
@@ -2284,7 +2939,11 @@ restriction on the maximum sub-entry depth.
To arrange a glossary with hierarchical categories, you need to
first define the category and then define the sub-entries using the
relevant category entry as the value of the \gloskey{parent} key.
-For example, suppose I want a glossary of mathematical symbols that
+
+\begin{example}{Hierarchical Categories---Greek and Roman
+Mathematical Symbols}{ex:hierarchical}
+
+Suppose I want a glossary of mathematical symbols that
are divided into Greek letters and Roman letters. Then I can define
the categories as follows:
\begin{verbatim}
@@ -2311,7 +2970,8 @@ parent=greekletter}
description={Euler's constant},
parent=romanletter}
\end{verbatim}
-
+For a complete document, see the sample file \samplefile{tree}.
+\end{example}
\subsection{Homographs}
\label{sec:homographs}
@@ -2346,7 +3006,8 @@ added to the parent's \gls{numberlist}, whereas if I reference any
of the child entries, the location will be added to the child
entry's number list. Note also that since the sub-entries have the
same name, the \gloskey{sort} key is required unless you are using
-the \pkgopt[use]{sort} or \pkgopt[def]{sort} package options. You
+the \pkgopt[use]{sort} or \pkgopt[def]{sort} package options (see
+\sectionref{sec:pkgopts-sort}). You
can use the \pkgopt{subentrycounter} package option to automatically
number the first-level child entries. See
\sectionref{sec:pkgopts-printglos} for further details.
@@ -2382,13 +3043,16 @@ file and use:
\cs{loadglsentries}\oarg{type}\marg{filename}
\end{definition}
where \meta{filename} is the name of the file containing all the
-\ics{newglossaryentry} commands. The optional argument
+\ics{newglossaryentry} or \ics{longnewglossaryentry} 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 (or, more specifically, for those entries whose
type has been specified by \ics{glsdefaulttype}, which is what
-\ics{newglossaryentry} uses by default). For example, suppose I have
-a file called \texttt{myentries.tex} which contains:
+\ics{newglossaryentry} uses by default).
+
+\begin{example}{Loading Entries from Another File}{ex:loadgls}
+Suppose I have a file called \texttt{myentries.tex} which contains:
\begin{verbatim}
\newglossaryentry{perl}{type=main,
name={Perl},
@@ -2409,6 +3073,7 @@ 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}.
+\end{example}
\textbf{Note:} if you use \ics{newacronym} (see
\sectionref{sec:acronyms}) the type is set as
@@ -2446,7 +3111,7 @@ and do:
\item Temporarily change \cs{acronymtype} to the target glossary:
\begin{verbatim}
\let\orgacronymtype\acronymtype
-\def\acronymtype{altacronym}
+\renewcommand{\acronymtype}{altacronym}
\loadglsentries{myacronyms}
\let\acronymtype\orgacronymtype
\end{verbatim}
@@ -2473,7 +3138,7 @@ Note that no check is performed to determine the existence of
the target glossary. This means that you can, for example, move an
entry to an undefined glossary so you can use the entry in the
document text but not have it listed in any of the glossaries.
-(Maybe you have an acronym so common it doesn't need listing.)
+(Maybe you have an acronym that is so common it doesn't need listing.)
\begin{important}
If you move an entry to an undefined glossary and you have
@@ -2486,6 +3151,68 @@ results may occur if you move an entry to a different glossary from
its parent or children.
\end{important}
+\section{Drawbacks With Defining Entries in the Document Environment}
+\label{sec:docdefs}
+
+Originally, \ics{newglossaryentry} (and \ics{newacronym}) could only be
+used in the preamble. I reluctantly removed this restriction in version 1.13,
+but there are issues with defining commands in the \env{document}
+environment instead of the preamble.
+
+\subsection{Technical Issues}
+\label{sec:techissues}
+
+\begin{enumerate}
+ \item If you define an entry mid-way through your document, but
+subsequently shuffle sections around, you could end up using an
+entry before it has been defined.
+
+ \item Entry information is required when the glossary is displayed
+using \ics{printglossary} or \ics{printglossaries}. When either of these
+commands occur at the start of the document, the entry details are
+being looked up before the entry has been defined.
+\end{enumerate}
+
+To overcome these problems, \sty{glossaries} v4.0 modifies the
+definition of \cs{newglossaryentry} at the beginning of the
+\env{document} environment so that the definitions are written to an
+external file (\cs{jobname}.\texttt{glsdefs}) which is then read in
+at the start of the document on the next run. The entry will then
+only be defined if it doesn't already exist. This means that the
+entry can now be looked up in the glossary, even if the glossary
+occurs at the beginning of the document.
+
+There are drawbacks to this mechanism: if you modify an entry
+definition, you need a second run to see the effect of your
+modification; this method requires an extra \cs{newwrite}, which may exceed
+\TeX's maximum allocation; if you have very long entries, you could
+find unexpected line breaks have been written to the temporary file.
+
+The last reason is why \ics{longnewglossaryentry} has the
+preamble-only restriction, which I don't intend to lift.
+
+\subsection{Good Practice Issues}
+\label{sec:goodpractice}
+
+The above section covers technical issues that can cause your document to have
+compilation errors or produce incorrect output. This section
+focuses on good writing practice. The main reason cited by users
+wanting to define entries within the \env{document} environment rather
+than in the preamble is that they want to write the definition as
+they type in their document text. This suggests a \qt{stream of
+consciousness} style of writing that may be acceptable in certain
+literary genres but is inappropriate for factual documents.
+
+When you write technical documents, regardless of whether it's a PhD
+thesis or an article for a~journal or proceedings, you must plan what you write
+in advance. If you plan in advance, you should have a fairly good
+idea of the type of terminology that your document will contain,
+so while you are planning, create a new file with all your entry
+definitions. If while you're writing your document, you remember
+another term you need, then you can switch over to your definition file and
+add it. Most text editors have the ability to have more than one
+file open at a time.
+
\chapter{Number lists}
\label{sec:numberlists}
@@ -2496,8 +3223,7 @@ been used (using any of the commands described in
list can be suppressed using the \pkgopt{nonumberlist} package
option, or an alternative counter can be set as the default using
the \pkgopt{counter} package option. The number list is also
-referred to as the location list\index{location list|see{number
-list}}.
+referred to as the location list\index{location list|see{number list}}.
Both \gls{makeindex} and \gls{xindy} concatenate a
sequence of 3 or more consecutive pages into a range. With
@@ -2572,7 +3298,7 @@ The above warning is particularly important if you are using the
\styfmt{glossaries} package in conjunction with the \sty{hyperref}
package. Instead, use one of the commands listed in
\sectionref{sec:glsnolink} (such as \ics{glsentrytext}) or provide an
-alternative via the optional argument to the sectioning/caption
+alternative via the optional argument to the sectioning\slash caption
command. Examples:
\begin{verbatim}
\chapter{An overview of \glsentrytext{perl}}
@@ -2587,6 +3313,21 @@ hyperlinked term, such as \gls{linktext}, you can click on the word
or phrase and it will take you to a brief description in this
document's glossary.
+\begin{important}
+If you use the \sty{hyperref} package, I strongly recommend you use
+\app{pdflatex} rather than \app{latex} to compile your document, if
+possible. The DVI format of \LaTeX\ has limitations with the
+hyperlinks that can cause a problem when used with the
+\sty{glossaries} package. Firstly, the DVI format can't break a
+hyperlink across a line whereas PDF\LaTeX\ can. This means that long
+glossary entries (for example, the full form of an acronym) won't be
+able to break across a line with the DVI format. Secondly, the DVI
+format doesn't correctly size hyperlinks in subscripts or
+superscripts. This means that if you define a term that may be used
+as a subscript or superscript, if you use the DVI format, it won't
+come out the correct size.
+\end{important}
+
It may be that you only want terms in a certain glossary to have
links, but not for another glossary. In which case, you can use the
package option \pkgopt{nohypertypes} to identify the glossary lists
@@ -2770,7 +3511,7 @@ that either has been listed in the package option
\ics{GlsDeclareNoHyperList} in which case the default is
\texttt{hyper=false}.
-\item[\gloskey{glslink}{local}] This is a boolean key that only
+\item[{\gloskey[glslink]{local}}] This is a boolean key that only
makes a different when used with commands that change the
entry's \gls{firstuseflag} (such as \ics{gls}). If
\texttt{local=true}, the change to the \gls*{firstuseflag} will be
@@ -2899,6 +3640,12 @@ There are also analogous commands:
As before, these commands also have a starred version that disable
the hyperlink.
+\begin{important}
+When used with acronyms, these commands don't use \ics{acronymfont}.
+For example, if you use the \pkgopt{smallcaps} package option,
+\cs{gls} will use small caps but \cs{glstext} won't.
+\end{important}
+
The command:
\begin{definition}[\DescribeMacro{\glsfirst}]
\cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}
@@ -2937,6 +3684,12 @@ There are also analogous commands:
As before, these commands also have a starred version that disable
the hyperlink.
+\begin{important}
+When used with acronyms, these commands don't use \ics{acronymfont}.
+For example, if you use the \pkgopt{smallcaps} package option,
+\cs{glspl} will use small caps but \cs{glsplural} won't.
+\end{important}
+
The command:
\begin{definition}[\DescribeMacro{\glsfirstplural}]
\cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert}
@@ -2963,10 +3716,7 @@ The command:
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
-\glsation{sanitize} of the \gloskey{name} key and
-protect fragile commands.
+used.
There are also analogous commands:
\begin{definition}[\DescribeMacro{\Glsname}]
@@ -2985,10 +3735,7 @@ The command:
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
-\glsation{sanitize} of the \gloskey{symbol} key and
-protect fragile commands.
+used.
There are also analogous commands:
\begin{definition}[\DescribeMacro{\Glssymbol}]
@@ -3007,10 +3754,7 @@ The command:
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 \glsation{sanitize} of the
-\gloskey{description} key and protect fragile commands.
+having been used.
There are also analogous commands:
\begin{definition}[\DescribeMacro{\Glsdesc}]
@@ -3090,60 +3834,67 @@ the hyperlink. Similarly for the other user keys:
\label{sec:glsdisplay}
The format of the \gls{linktext} for \ics{gls}, \ics{glspl}
-and their uppercase variants is governed by two commands:
-\begin{definition}[\DescribeMacro{\glsdisplayfirst}]
-\cs{glsdisplayfirst}\marg{first/first plural}\marg{description}\marg{symbol}\marg{insert}
-\end{definition}
-which is used the
-\glslink{firstuse}{first time} a glossary entry is used in the text and
-\begin{definition}[\DescribeMacro{\glsdisplay}]
-\cs{glsdisplay}\marg{text/plural}\marg{description}\marg{symbol}\marg{insert}
-\end{definition}
-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 (set when the term was
-defined) depending on context; the second argument is the term's
-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} or \gloskey{symbolplural} keys) and the fourth argument is the additional text
-supplied in the final optional argument to \ics{gls} or
-\ics{glspl} (or their uppercase variants). The default definitions
-of \cs{glsdisplay} and \cs{glsdisplayfirst} simply
-print the first argument immediately followed by the fourth argument.
-The remaining arguments are ignored.
-
-\begin{important}
-Care needs to be taken when redefining \cs{glsdisplay} and
-\cs{glsdisplayfirst} as commands like \ics{Gls} will expand the
-displayed text before applying \ics{makefirstuc}. If you want to use
-formatting commands, it's best to define a robust version that deals
-with all the formatting. For example, suppose you want
-the text to appear in bold italic, it's best to do something like:
-\begin{verbatim}
-\DeclareRobustCommand{\textbfit}[1]{\emph{\bfseries
-#1}}
-\renewcommand{\glsdisplay}[4]{\textbfit{#1#4}}
-\end{verbatim}
-See the \sty{mfirstuc} documentation for further details on the
-limitations of \ics{makefirstuc}.
-\end{important}
+and their uppercase variants and also for \ics{glsdisp} is governed
+by\footnote{\ics{glsdisplayfirst} and \ics{glsdisplay} are now
+deprecated. Backwards compatibility should be preserved but
+you may need to use the \pkgopt{compatible-3.07} option}:
+\begin{definition}[\DescribeMacro{\glsentryfmt}]
+\cs{glsentryfmt}
+\end{definition}
+If you want to redefine this command, you may use the following
+commands within its definition:
-If required, you can access the label for the given entry via
\begin{definition}[\DescribeMacro{\glslabel}]
\cs{glslabel}
\end{definition}
-so it is possible to use this label in the definition of
-\cs{glsdisplay} or \cs{glsdisplayfirst} to supply additional
-information using any of the commands described in
-\sectionref{sec:glsnolink}, if required.
+This is the label of the entry being referenced.
+
+\begin{definition}[\DescribeMacro{\glscustomtext}]
+\cs{glscustomtext}
+\end{definition}
+This is the custom text supplied in \cs{glsdisp}. It's always empty
+for \ics{gls}, \ics{glspl} and their uppercase variants. (You can
+use \sty{etoolbox}'s \cs{ifdefempty} to determine if
+\cs{glscustomtext} is empty.)
+
+\begin{definition}[\DescribeMacro{\glsinsert}]
+\cs{glsinsert}
+\end{definition}
+The custom text supplied in the final optional argument to \cs{gls},
+\cs{glspl} and their uppercase variants.
+
+\begin{definition}[\DescribeMacro{\glsifplural}]
+\cs{glsifplural}\marg{true text}\marg{false text}
+\end{definition}
+If \cs{glspl}, \cs{Glspl} or \cs{GLSpl} was used, this command does
+\meta{true text} otherwise it does \meta{false text}.
+
+\begin{definition}[\DescribeMacro{\glscapscase}]
+\cs{glscapscase}\marg{no case}\marg{first uc}\marg{all caps}
+\end{definition}
+If \cs{gls}, \cs{glspl} or \cs{glsdisp} were used, this does \meta{no
+case}. If \cs{Gls} or \cs{Glspl} were used, this does \meta{first
+uc}. If \cs{GLS} or \cs{GLSpl} were used, this does \meta{all caps}.
-Note that \cs{glsdisplay} and \cs{glsdisplayfirst} are not used
-by \ics{glslink}. If you want to supply your own link text, you
-need to use \ics{glsdisp} instead.
+Note that you can also use commands such as \ics{ifglsused} within
+the definition of \cs{glsentryfmt} (see \sectionref{sec:glsunset}).
-For example, suppose you want a glossary of measurements and
+If you only want to make minor modifications to \cs{glsentryfmt},
+you can use
+\begin{definition}[\DescribeMacro{\glsgenentryfmt}]
+\cs{glsgenentryfmt}
+\end{definition}
+This uses the above commands to display just the \gloskey{first},
+\gloskey{text}, \gloskey{plural} or \gloskey{firstplural} keys
+(or the custom text) with the insert text appended.
+
+\begin{important}
+Note that \cs{glsentryfmt} is not used by \ics{glslink} or any of
+the other commands, such as \ics{glstext}.
+\end{important}
+
+\begin{example}{Custom Entry Display in Text}{ex:customfmt}
+Suppose you want a glossary of measurements and
units, you can use the \gloskey{symbol} key to store the unit:
\begin{verbatim}
\newglossaryentry{distance}{name=distance,
@@ -3152,54 +3903,52 @@ symbol={km}}
\end{verbatim}
and now suppose you want \verb|\gls{distance}| to produce
\qt{distance (km)} on \firstuse, then you can redefine
-\cs{glsdisplayfirst} as follows:
+\ics{glsentryfmt} as follows:
\begin{verbatim}
-\renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)}
+\renewcommand*{\glsentryfmt}{%
+ \glsgenentryfmt
+ \ifglsused{\glslabel}{}{\space (\glsentrysymbol{\glslabel})}%
+}
\end{verbatim}
-Note that the additional text is placed after \verb|#1|, so
-\verb|\gls{distance}['s]| will produce \qt{distance's (km)}
-rather than \qt{distance (km)'s} which looks a bit odd (even though
-it may be in the context of \qt{the distance (km) is measured between
-the two points} --- but in this instance it would be better not to
-use a contraction).
+
+(Note that I've used \ics{glsentrysymbol} rather than \ics{glssymbol}
+to avoid nested hyperlinks.)
Note also that all of the \gls{linktext} will be formatted according
to \ics{glstextformat} (described earlier). So if you do, say:
\begin{verbatim}
\renewcommand{\glstextformat}[1]{\textbf{#1}}
-\renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)}
+\renewcommand*{\glsentryfmt}{%
+ \glsgenentryfmt
+ \ifglsused{\glslabel}{}{\space(\glsentrysymbol{\glslabel})}%
+}
\end{verbatim}
then \verb|\gls{distance}| will produce \qt{\textbf{distance (km)}}.
-If you have multiple glossaries, changing \cs{glsdisplayfirst} and
-\cs{glsdisplay} will change the way entries for all of the
-glossaries appear when using the commands \ics{gls}, \ics{glspl}, their
-uppercase variants and \ics{glsdisp}. If you only
+For a complete document, see the sample file \samplefile{-entryfmt}.
+\end{example}
+
+If you have multiple glossaries, changing \cs{glsentryfmt} will change the
+way entries for all of the glossaries appear when using the commands
+\ics{gls}, \ics{glspl}, their uppercase variants and \ics{glsdisp}.
+If you only
want the change to affect entries for a given glossary, then you need
to use
-\begin{definition}[\DescribeMacro{\defglsdisplay}]
-\cs{defglsdisplay}\oarg{type}\marg{definition}
-\end{definition}
-and
-\begin{definition}[\DescribeMacro{\defglsdisplayfirst}]
-\cs{defglsdisplayfirst}\oarg{type}\marg{definition}
+\begin{definition}[\DescribeMacro{\defglsentryfmt}]
+\cs{defglsentryfmt}\oarg{type}\marg{definition}
\end{definition}
-instead of redefining \cs{glsdisplay} and \cs{glsdisplayfirst}.
+instead of redefining \cs{glsentryfmt}. The optional first argument
+\meta{type} is the glossary type. This defaults to
+\ics{glsdefaulttype} if omitted. The second argument is the
+entry format definition.
-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
-(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
-displayed when it is invoked using commands \cs{gls},
-\cs{glspl}, their uppercase variants and \cs{glsdisp}. This is similar to the way \cs{glsdisplayfirst} was
-redefined above.
-
-For example, suppose you have created a new glossary called
+\begin{example}{Custom Format for Particular Glossary}{ex:defglsentryfmt}
+Suppose you have created a new glossary called
\texttt{notation} and you want to change the way the entry is
displayed on \firstuse\ so that it includes the symbol, you can do:
\begin{verbatim}
-\defglsdisplayfirst[notation]{#1#4 (denoted #3)}
+\defglsentryfmt[notation]{\glsgenentryfmt
+ \ifglsused{\glslabel}{}{\space(denoted \glsentrysymbol{\glslabel})}}
\end{verbatim}
Now suppose you have defined an entry as follows:
\begin{verbatim}
@@ -3211,13 +3960,11 @@ Now suppose you have defined an entry as follows:
\end{verbatim}
The \glslink{firstuse}{first time} you reference this entry it will be displayed as:
\qt{set (denoted $S$)} (assuming \ics{gls} was used).
+\end{example}
Remember that if you use the \gloskey{symbol} key, you need to use a
glossary style that displays the symbol, as many of the styles
-ignore it. In addition, if you want either the description or symbol
-to appear in the \gls{linktext}, you will have to disable the
-\glsation{sanitize} of these keys and protect fragile
-commands.
+ignore it.
\section{Enabling and disabling hyperlinks to glossary entries}
\label{sec:disablehyperlinks}
@@ -3244,6 +3991,90 @@ option \pkgopt[false]{hyperfirst}. Note that this option only
affects commands that recognise the \firstuseflag, for example
\ics{gls}, \ics{glspl} and \ics{glsdisp} but not \ics{glslink}.
+\begin{example}{First Use With Hyperlinked Footnote Description}{ex:hyperdesc}
+Suppose I want the \gls*{firstuse} to have a hyperlink to the
+description in a footnote instead of hyperlinking to the relevant
+place in the glossary. First I need to disable the hyperlinks on
+first use via the package option \pkgopt[false]{hyperfirst}:
+\begin{verbatim}
+\usepackage[hyperfirst=false]{glossaries}
+\end{verbatim}
+Now I need to redefine \ics{glsentryfmt} (see
+\sectionref{sec:glsdisplay}):
+\begin{verbatim}
+\renewcommand*{\glsentryfmt}{%
+ \glsgenentryfmt
+ \ifglsused{\glslabel}{}{\footnote{\glsentrydesc{\glslabel}}}%
+}
+\end{verbatim}
+
+Now the first use won't have hyperlinked text, but will be followed
+by a footnote.
+See the sample file \samplefile{-FnDesc} for a complete document.
+\end{example}
+
+Note that the \pkgopt{hyperfirst} option applies to all defined glossaries. It
+may be that you only want to disable the hyperlinks on
+\gls{firstuse} for glossaries that have a different form on
+\gls*{firstuse}. This can be achieved by noting that since the
+entries that require hyperlinking for all instances have identical
+first and subsequent text, they can be unset via \ics{glsunsetall}
+(see \sectionref{sec:glsunset}) so that the \pkgopt{hyperfirst}
+option doesn't get applied.
+
+\begin{example}{Suppressing Hyperlinks on First Use Just For
+Acronyms}{ex:hyperfirst}
+Suppose I want to suppress the hyperlink on \gls{firstuse} for
+acronyms but not for entries in the main glossary. I~can load
+the \styfmt{glossaries} package using:
+\begin{verbatim}
+\usepackage[hyperfirst=false,acronym]{glossaries}
+\end{verbatim}
+Once all glossary entries have been defined I~then do:
+\begin{verbatim}
+\glsunsetall[main]
+\end{verbatim}
+
+\end{example}
+
+For more complex requirements, you might find it easier to switch
+off all hyperlinks via \ics{glsdisablehyper} and put the hyperlinks
+(where required) within the definition of \ics{glsentryfmt} (see
+\sectionref{sec:glsdisplay}) via \ics{glshyperlink} (see
+\sectionref{sec:glsnolink}).
+
+\begin{example}{Only Hyperlink in Text Mode Not Math
+Mode}{ex:nomathhyper}
+This is a bit of a contrived example, but suppose, for some reason,
+I only want commands like \ics{gls} and \ics{glsdisp} to have
+hyperlinks when used in text mode, but not in math mode. I~can do
+this by disabling all hyperlinks and redefining \ics{glsentryfmt}:
+\begin{verbatim}
+\glsdisablehyper
+\renewcommand*{\glsentryfmt}{%
+ \ifmmode
+ \glsgenentryfmt
+ \else
+ % Temporarily enable hyperlinks:
+ \glsenablehyper
+ \glshyperlink[\glsgenentryfmt]{\glslabel}%
+ % Disable hyperlinks again
+ \glsdisablehyper
+ \fi
+}
+\end{verbatim}
+To ensure the target exists, the hyperlinks must be enabled again
+when the glossary is displayed:
+\begin{verbatim}
+\renewcommand{\glossarypreamble}{\glsenablehyper}
+\renewcommand{\glossarypostamble}{\glsdisablehyper}
+\end{verbatim}
+(The redefinition of \ics{glossarypostamble} is only necessary if
+the glossary is displayed at the start of the document instead of at
+the end.)
+See the sample file \samplefile{-nomathhyper} for a complete
+document.
+\end{example}
\chapter{Adding an Entry to the Glossary Without Generating Text}
\label{sec:glsadd}
@@ -3283,13 +4114,24 @@ do:
\begin{important}
Note that \cs{glsadd} and \cs{glsaddall} add the current location to
-the number list. In the case of \cs{glsaddall}, all entries in the
+the \gls{numberlist}. In the case of \cs{glsaddall}, all entries in the
glossary will have the same location in the number list. If you want
to use \cs{glsaddall}, it's best to suppress the number list with
the \pkgopt{nonumberlist} package option. (See
sections~\ref{sec:pkgopts-printglos} and~\ref{sec:numberlists}.)
\end{important}
+There is now a variation of \cs{glsaddall} that skips any entries
+that have already been used:
+\begin{definition}[\DescribeMacro\glsaddallunused]
+\cs{glsaddallunused}\oarg{list}
+\end{definition}
+This command uses \cs{glsadd}\texttt{[format=@gobble]} which will
+ignore this location in the number list. The optional argument
+\meta{list} is a comma-separated list of glossary types. If omitted,
+it defaults to the list of all defined glossaries.
+
+\begin{example}{Dual Entries}{ex:dual}
The sample file \samplefile{-dual} makes use of \cs{glsadd} to
allow for an entry that should appear both in the main glossary and
in the list of acronyms. This example sets up the list of acronyms
@@ -3302,11 +4144,11 @@ entries:
\begin{verbatim}
\newcommand*{\newdualentry}[5][]{%
\newglossaryentry{main-#2}{name={#4},%
- text={#3\protect\glsadd{#2}},%
+ text={#3\glsadd{#2}},%
description={#5},%
#1
}%
- \newacronym{#2}{#3\protect\glsadd{main-#2}}{#4}
+ \newacronym{#2}{#3\glsadd{main-#2}}{#4}%
}
\end{verbatim}
This has the following syntax:
@@ -3322,6 +4164,7 @@ You can then define a new dual entry:
\end{verbatim}
Now you can reference the acronym with \verb|\gls{svm}| or you can
reference the entry in the main glossary with \verb|\gls{main-svm}|.
+\end{example}
\chapter{Cross-Referencing Entries}
\label{sec:crossref}
@@ -3354,17 +4197,6 @@ makeglossaries filename
latex filename
\end{verbatim}
-\begin{important}
-If you switch off the description
-\glsation{sanitize}, you must protect fragile
-commands:\footnote{As from v3.01, \ics{gls} is no longer fragile.}
-\begin{verbatim}
-\newglossaryentry{apple}{name=apple,
-description={firm, round fruit. See also
-\protect\gls{pear}}}
-\end{verbatim}
-\end{important}
-
\item As described in \sectionref{sec:newglosentry}, you can use the
\gloskey{see} key when you define the entry. For example:
\begin{verbatim}
@@ -3469,8 +4301,8 @@ is displayed using:
\cs{glsseeitemformat}\marg{label}
\end{definition}
This defaults to \ics{glsentrytext}\marg{label}.\footnote{In
-versions before 3.0, \cs{glsentryname} was used, but this can cause
-problems when the \gloskey{name} key is \glsd{sanitize}.} For example, to
+versions before 3.0, \cs{glsentryname} was used, but this could cause
+problems when the \gloskey{name} key was \glsd{sanitize}.} For example, to
make the cross-referenced list use small caps:
\begin{verbatim}
\renewcommand{\glsseeitemformat}[1]{%
@@ -3497,6 +4329,15 @@ adding any information to the glossary. They don't use
\ics{glstextformat}, they don't have any optional arguments, they
don't affect the \firstuseflag\ and, apart from \ics{glshyperlink},
they don't produce hyperlinks.
+
+\begin{important}
+Commands that aren't expandable will be ignored by PDF bookmarks, so
+you will need to provide an alternative via \sty{hyperref}'s
+\cs{texorpdfstring} if you want to use them in sectioning commands.
+(This isn't specific to the \styfmt{glossaries} package.) See the
+\sty{hyperref} documentation for further details.
+\end{important}
+
\begin{definition}[\DescribeMacro{\glsentryname}]
\cs{glsentryname}\marg{label}
\end{definition}
@@ -3506,6 +4347,28 @@ they don't produce hyperlinks.
These commands display the name of the glossary entry given by
\meta{label}, as specified by the \gloskey{name} key.
\cs{Glsentryname} makes the first letter uppercase.
+Neither of these commands check for the existence of \meta{label}.
+The first form \cs{glsentryname} is expandable (unless the name
+contains unexpandable commands).
+
+\begin{definition}[\DescribeMacro{\glossentryname}]
+\cs{glossentryname}\marg{label}
+\end{definition}
+This is like \cs{glsnamefont}\{\cs{glsentryname\marg{label}}\}
+but also checks for the existence of \meta{label}. This command is
+not expandable. It's used in the predefined glossary styles, so if
+you want to change the way the name is formatted in the glossary,
+you can redefine \cs{glsnamefont} to use the required fonts. For
+example:
+\begin{verbatim}
+\renewcommand*{\glsnamefont}[1]{\textmd{\sffamily #1}}
+\end{verbatim}
+\begin{definition}[\DescribeMacro{\Glossentryname}]
+\cs{Glossentryname}\marg{label}
+\end{definition}
+This is like \cs{glossentryname} but makes the first letter of the
+name uppercase.
+
\begin{definition}[\DescribeMacro{\glsentrytext}]
\cs{glsentrytext}\marg{label}
\end{definition}
@@ -3515,6 +4378,10 @@ These commands display the name of the glossary entry given by
These commands display the subsequent use text for the glossary
entry given by \meta{label}, as specified by the \gloskey{text} key.
\cs{Glsentrytext} makes the first letter uppercase.
+The first form is expandable (unless the text contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
\begin{definition}[\DescribeMacro{\glsentryplural}]
\cs{glsentryplural}\marg{label}
\end{definition}
@@ -3525,6 +4392,10 @@ These commands display the subsequent use plural text for the
glossary entry given by \meta{label}, as specified by the
\gloskey{plural} key. \cs{Glsentryplural} makes the first letter
uppercase.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
\begin{definition}[\DescribeMacro{\glsentryfirst}]
\cs{glsentryfirst}\marg{label}
\end{definition}
@@ -3534,6 +4405,10 @@ uppercase.
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.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
\begin{definition}[\DescribeMacro{\glsentryfirstplural}]
\cs{glsentryfirstplural}\marg{label}
\end{definition}
@@ -3544,6 +4419,10 @@ 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.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
\begin{definition}[\DescribeMacro{\glsentrydesc}]
\cs{glsentrydesc}\marg{label}
\end{definition}
@@ -3552,6 +4431,23 @@ letter uppercase.
\end{definition}
These commands display the description for the glossary entry given
by \meta{label}. \cs{Glsentrydesc} makes the first letter uppercase.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+\begin{definition}[\DescribeMacro{\glossentrydesc}]
+\cs{glossentrydesc}\marg{label}
+\end{definition}
+This is like \cs{glsentrydesc}\marg{label}
+but also checks for the existence of \meta{label}. This command is
+not expandable. It's used in the predefined glossary styles to
+display the description.
+\begin{definition}[\DescribeMacro{\Glossentrydesc}]
+\cs{Glossentrydesc}\marg{label}
+\end{definition}
+This is like \cs{glossentrydesc} but converts the first letter to
+uppercase. This command is not expandable.
+
\begin{definition}[\DescribeMacro{\glsentrydescplural}]
\cs{glsentrydescplural}\marg{label}
\end{definition}
@@ -3561,6 +4457,11 @@ by \meta{label}. \cs{Glsentrydesc} makes the first letter uppercase.
These commands display the plural description for the glossary entry
given by \meta{label}. \cs{Glsentrydescplural} makes the first
letter uppercase.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+
\begin{definition}[\DescribeMacro{\glsentrysymbol}]
\cs{glsentrysymbol}\marg{label}
\end{definition}
@@ -3569,6 +4470,23 @@ letter uppercase.
\end{definition}
These commands display the symbol for the glossary entry given by
\meta{label}. \cs{Glsentrysymbol} makes the first letter uppercase.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
+\begin{definition}[\DescribeMacro{\glossentrysymbol}]
+\cs{glossentrysymbol}\marg{label}
+\end{definition}
+This is like \cs{glsentrysymbol}\marg{label}
+but also checks for the existence of \meta{label}. This command is
+not expandable. It's used in the predefined glossary styles to
+display the symbol.
+\begin{definition}[\DescribeMacro{\Glossentrysymbol}]
+\cs{Glossentrysymbol}\marg{label}
+\end{definition}
+This is like \cs{glossentrysymbol} but converts the first letter to
+uppercase. This command is not expandable.
+
\begin{definition}[\DescribeMacro{\glsentrysymbolplural}]
\cs{glsentrysymbolplural}\marg{label}
\end{definition}
@@ -3578,6 +4496,10 @@ These commands display the symbol for the glossary entry given by
These commands display the plural symbol for the glossary entry
given by \meta{label}. \cs{Glsentrysymbolplural} makes the first
letter uppercase.
+The first form is expandable (unless the value of that key contains unexpandable
+commands). The second form is not expandable. Neither checks for the
+existence of \meta{label}.
+
\begin{definition}[\DescribeMacro{\glsentryuseri}]
\cs{glsentryuseri}\marg{label}
\end{definition}
@@ -3616,6 +4538,12 @@ letter uppercase.
\end{definition}
These commands display the value of the user keys for the glossary
entry given by \meta{label}.
+The lower case forms are expandable (unless the value of the key
+contains unexpandable commands). The commands beginning with an
+uppercase letter convert the first letter of the required value to
+uppercase and are not expandable. None of these commands check for
+the existence of \meta{label}.
+
\begin{definition}[\DescribeMacro{\glshyperlink}]
\cs{glshyperlink}\oarg{link text}\marg{label}
\end{definition}
@@ -3623,8 +4551,8 @@ This command provides a hyperlink to the glossary entry given by
\meta{label} \textbf{but does not add any information to the
glossary file}. The link text is given by
\ics{glsentrytext}\marg{label} by default\footnote{versions before
-3.0 used \ics{glsentryname} as the default, but this can cause
-problems when \gloskey{name} has been \glsd{sanitize}.}, but can be
+3.0 used \ics{glsentryname} as the default, but this could cause
+problems when \gloskey{name} had been \glsd{sanitize}.}, but can be
overridden using the optional argument.
\begin{important}
If you use \cs{glshyperlink}, you need to ensure that the relevant
@@ -3682,7 +4610,7 @@ used the Perl script \gls{makeglossaries} or have directly used
\gls{makeindex} or \gls{xindy} (as described in
\sectionref{sec:makeglossaries}). If the glossary
still does not appear after you re-\LaTeX\ your document, check the
-\gls*{makeindex}/\gls*{xindy} log files to see if there is a problem.
+\gls*{makeindex}\slash\gls*{xindy} log files to see if there is a problem.
Remember that you also need to use the command \ics{makeglossaries}
in the preamble to enable the glossaries.
@@ -3733,9 +4661,12 @@ By default, the glossary is started either by \ics{chapter*} or by
This can be overridden by the \pkgopt{section} package option or the
\linebreak\ics{setglossarysection} command. Numbered sectional units can be
obtained using the \pkgopt{numberedsection} package option. Each
-glossary sets the page header via the command \ics{glossarymark}. If
-this mechanism is unsuitable for your chosen class file or page
-style package, you will need to redefine \ics{glossarymark}. Further
+glossary sets the page header via the command
+\begin{definition}[\DescribeMacro\glsglossarymark]
+\ics{glsglossarymark}\marg{title}
+\end{definition}
+If this mechanism is unsuitable for your chosen class file or page
+style package, you will need to redefine \ics{glsglossarymark}. Further
information about these options and commands is given in
\sectionref{sec:pkgopts-sec}.
@@ -3766,13 +4697,14 @@ indicate primary definitions.}
This will print the given preamble text for the main glossary,
but not have any preamble text for any other glossaries.
-There is an analogous command called
+There is an analogous command to \cs{glossarypreamble} called
\begin{definition}[\DescribeMacro{\glossarypostamble}]
\cs{glossarypostamble}
\end{definition}
which is placed at the end of each glossary.
-For example: suppose you are using the \glostyle{superheaderborder}
+\begin{example}{Switch to Two Column Mode for Glossary}{ex:twocolumn}
+Suppose you are using the \glostyle{superheaderborder}
style\footnote{you can't use the \glostyle{longheaderborder} style
for this example as you can't use the \env{longtable} environment in
two column mode.}, and you want the glossary to be in two columns,
@@ -3782,12 +4714,14 @@ you could do:
\renewcommand*{\glossarysection}[2][]{%
\twocolumn[{\chapter*{#2}}]%
\setlength\glsdescwidth{0.6\linewidth}%
- \glossarymark{\glossarytoctitle}%
+ \glsglossarymark{\glossarytoctitle}%
}
\renewcommand*{\glossarypostamble}{\onecolumn}
\end{verbatim}
+\end{example}
+
Within each glossary, each entry name is formatted according to
\begin{definition}[\DescribeMacro{\glsnamefont}]
\cs{glsnamefont}\marg{name}
@@ -3804,12 +4738,14 @@ will appear in the normal font. The hierarchical glossary styles
(defined in the \sty{glossary-tree} style file) also set the name in
bold.
-For example, suppose you want all the entry names to appear in
-medium weight small caps, then you can do:
+\begin{example}{Changing the Font Used to Display Entry Names in the
+Glossary}{ex:glsnamefont}
+Suppose you want all the entry names to appear in
+medium weight small caps in your glossaries, then you can do:
\begin{verbatim}
\renewcommand{\glsnamefont}[1]{\textsc{\mdseries #1}}
\end{verbatim}
-
+\end{example}
\chapter{Xindy}
\label{sec:xindy}
@@ -3856,7 +4792,10 @@ available through the \LaTeX\ commands provided by the
style file. In which case, you must use \ics{noist} to prevent the
style file from being overwritten by the \styfmt{glossaries}
package. For additional information about \gls*{xindy}, read the
-\gls*{xindy} documentation.
+\gls*{xindy} documentation. I'm sorry I can't provide any assistance
+with writing \gls*{xindy} style files. If you need help, I recommend
+you ask on the \gls*{xindy} mailing list
+(\url{http://xindy.sourceforge.net/mailing-list.html}).
\section{Language and Encodings}
\label{sec:langenc}
@@ -3866,10 +4805,10 @@ and encoding used (unless you have written your own custom
\gls*{xindy} style file that defines the relevant alphabet
and sort rules). If you use \gls{makeglossaries},
this information is obtained from the document's auxiliary
-(\filetype{.aux}) file. The \styfmt{glossaries} package attempts to
-find the root language, but in the event that it gets it wrong or if
-\gls*{xindy} doesn't support that language, then you can
-specify the language using:
+(\filetype{.aux}) file. The \gls{makeglossaries} script attempts to
+find the root language given your document settings, but in the
+event that it gets it wrong or if \gls*{xindy} doesn't support
+that language, then you can specify the required language using:
\begin{definition}[\DescribeMacro{\GlsSetXdyLanguage}]
\cs{GlsSetXdyLanguage}\oarg{glossary type}\marg{language}
\end{definition}
@@ -3941,8 +4880,10 @@ attribute, you need to add it using:
\cs{GlsAddXdyAttribute}\marg{name}
\end{definition}
where \meta{name} is the name of the attribute, as used in
-the \gloskey[glslink]{format} key. For example, suppose I want a
-bold, italic, hyperlinked location. I first need to define a
+the \gloskey[glslink]{format} key.
+
+\begin{example}{Custom Font for Displaying a Location}{ex:hyperbfit}
+Suppose I want a bold, italic, hyperlinked location. I first need to define a
command that will do this:
\begin{verbatim}
\newcommand*{\hyperbfit}[1]{\textit{\hyperbf{#1}}}
@@ -3952,6 +4893,13 @@ attribute:
\begin{verbatim}
\GlsAddXdyAttribute{hyperbfit}
\end{verbatim}
+Now I can use it in the optional argument of commands like
+\ics{gls}:
+\begin{verbatim}
+Here is a \gls[format=hyperbfit]{sample} entry.
+\end{verbatim}
+(where \texttt{sample} is the label of the required entry).
+\end{example}
\begin{important}
Note that \cs{GlsAddXdyAttribute} has no effect if \ics{noist} is
@@ -3978,8 +4926,9 @@ used or if \ics{makeglossaries} is omitted.
\cs{GlsAddXdyLocation} must be used before \ics{makeglossaries}.
\end{important}
-For example, suppose I decide to use a somewhat eccentric numbering
-system for sections that redefines \cs{thesection} as follows:
+\begin{example}{Custom Numbering System for Locations}{ex:customloc}
+Suppose I decide to use a somewhat eccentric numbering
+system for sections where I redefine \cs{thesection} as follows:
\begin{verbatim}
\renewcommand*{\thesection}{[\thechapter]\arabic{section}}
\end{verbatim}
@@ -4015,17 +4964,19 @@ zero, it's a good idea to add an extra location to catch this:
"arabic-numbers" :sep "]" "arabic-numbers"
}
\end{verbatim}
-The above example is illustrated in the accompanying sample file
+This example is illustrated in the sample file
\samplefile{xdy2}.
+\end{example}
-Another example: suppose you want the page numbers written as words
-rather than digits and you use the \sty{fmtcount} package to
-do this. You can redefine \ics{thepage} as follows:
+\begin{example}{Locations as Words not Digits}{ex:fmtcount}
+Suppose I want the page numbers written as words
+rather than digits and I~use the \sty{fmtcount} package to
+do this. I~can redefine \ics{thepage} as follows:
\begin{verbatim}
\renewcommand*{\thepage}{\Numberstring{page}}
\end{verbatim}
This gets expanded to \verb|\protect \Numberstringnum |\marg{n}
-where \meta{n} is the Arabic page number. This means that you need to
+where \meta{n} is the Arabic page number. This means that I~need to
define a new location that has that form:
\begin{verbatim}
\GlsAddXdyLocation{Numberstring}{:sep "\string\protect\space
@@ -4036,7 +4987,8 @@ Note that it's necessary to use \cs{space} to indicate that
spaces also appear in the format, since, unlike \TeX,
\gls{xindy} doesn't ignore spaces after control sequences.
-\cs{GlsAddXdyLocation}\marg{name}\marg{definition} will define commands
+Note that \cs{GlsAddXdyLocation}\marg{name}\marg{definition} will define
+commands in the form:
\begin{definition}
\cs{glsX}\meta{counter}"X"\meta{name}\marg{Hprefix}\marg{location}
\end{definition}
@@ -4053,7 +5005,7 @@ uses the default \ics{glsnumberformat} and a custom \cs{hyperbfit}
format. A new \gls{xindy} location called \texttt{Numberstring}, as
illustrated above, is defined to make the page numbers appear as
\qt{One}, \qt{Two}, etc. In order for the location numbers to
-hyperlink to the relevant pages, I need to redefine the necessary
+hyperlink to the relevant pages, I~need to redefine the necessary
\cs{glsX}\meta{counter}"X"\meta{format} commands:
\begin{verbatim}
\renewcommand{\glsXpageXglsnumberformat}[2]{%
@@ -4066,6 +5018,7 @@ hyperlink to the relevant pages, I need to redefine the necessary
\newcommand{\linkpagenumber}[3]{\hyperlink{page.#3}{#1#2{#3}}}
\end{verbatim}
+\end{example}
In the \gls{numberlist}, the locations are sorted according to
type. The default ordering is: \texttt{roman-page-numbers} (e.g.\
@@ -4112,8 +5065,10 @@ Note that \cs{GlsSetXdyLocationClassOrder} has no effect if
If a \gls{numberlist} consists of a sequence of consecutive
numbers, the range will be concatenated. The
number of consecutive locations that causes a range formation
-defaults to 2, but can be changed using:
-\begin{definition}[\DescribeMacro{\GlsSetXdyMinRangeLength}]
+defaults to 2, but can be changed using:\newpage
+
+\DescribeMacro{\GlsSetXdyMinRangeLength}
+\begin{definition}
\cs{GlsSetXdyMinRangeLength}\marg{n}
\end{definition}
For example:
@@ -4124,7 +5079,7 @@ The argument may also be the keyword \texttt{none}, to indicate that
there should be no range formations. See the \gls{xindy}
manual for further details on range formations.
-\begin{important}
+\begin{important}\raggedright
Note that \cs{GlsSetXdyMinRangeLength} has no effect if \ics{noist}
is used or if \ics{makeglossaries} is omitted.
\cs{GlsSetXdyMinRangeLength} must be used before
@@ -4163,7 +5118,6 @@ Note that \cs{GlsSetXdyFirstLetterAfterDigits} has no effect if
\ics{makeglossaries}.\par
\end{important}
-
\chapter{Defining New Glossaries}
\label{sec:newglossary}
@@ -4202,15 +5156,27 @@ the main glossary as your list of acronyms, you need to declare
it as a list of acronyms using the package option
\pkgopt{acronymlists}.
+The \pkgopt{symbols} package option creates a new glossary with the
+label \texttt{symbols} using:
+\begin{verbatim}
+\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname}
+\end{verbatim}
+and the \pkgopt{numbers} package option creates a new glossary with
+the label \texttt{numbers} using:
+\begin{verbatim}
+\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname}
+\end{verbatim}
+
\begin{important}
All glossaries must be defined before \ics{makeglossaries} to
ensure that the relevant output files are opened.
See \sectionref{sec:fixednames} if you want to redefine \cs{glossaryname},
especially if you are using \sty{babel} or \sty{translator}.
+(Similarly for \cs{glssymbolsgroupname} and
+\cs{glsnumbersgroupname}.)
\end{important}
-
\chapter{Acronyms}
\label{sec:acronyms}
@@ -4220,15 +5186,14 @@ term is \glsd{firstuse} in the document. This provides a
useful means to define acronyms. For convenience, the
\styfmt{glossaries} package defines the command:
\begin{definition}[\DescribeMacro{\newacronym}]
-\cs{newacronym}\oarg{key-val
-list}\marg{label}\marg{abbrv}\marg{long}
+\cs{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}
\end{definition}
This uses \ics{newglossaryentry} to create an entry with the given
label in the glossary given by \ics{acronymtype}. Amongst other
things, it sets up the \gloskey{first} and \gloskey{text} keys and,
-depending on the acronym style, may also use \ics{defdisplayfirst}
-and \ics{defdisplay} (see \sectionref{sec:glsdisplay}).
+depending on the acronym style, may also use \ics{defglsentryfmt}
+(see \sectionref{sec:glsdisplay}).
The optional argument \marg{key-val list} allows you to specify keys
such as \gloskey{description} (when used with the
@@ -4270,12 +5235,24 @@ characters into small capitals and leaves upper case characters as
they are. Therefore, you need to have lower case characters in
\meta{abbrv} for this option to have an effect.)
+\hypertarget{boldsc}{}%
+\begin{important}%
+Some fonts don't support bold smallcaps, so you may need to redefine
+\ics{glsnamefont} (see \sectionref{sec:printglossary}) to switch to
+medium weight if you are using a glossary style that displays entry
+names in bold.
+\end{important}
+
\item[\pkgopt{smaller}]
This is similar to \pkgopt{smallcaps}, except that \ics{textsmaller}
is used instead of \ics{textsc}. Note that the \styfmt{glossaries}
package doesn't define \ics{textsmaller} nor does it load any
-package that does so. If you use this option, you must make sure
+package that does so.
+
+\begin{important}
+If you use this option, you must make sure
\ics{textsmaller} is defined (for example by loading \sty{relsize}).
+\end{important}
\item[\pkgopt{dua}]
This option will set both the \gloskey{first} and \gloskey{text}
@@ -4288,16 +5265,16 @@ If you want to define your own custom acronym style, see
\begin{important}
If you try using \ics{newglossaryentry} for entries in a designated
list of acronyms in combination with any of the above named package
-options you are likely to get unexpected results such as empty
+options you may get unexpected results such as empty
brackets or empty footnotes.
-If you don't intend to use \ics{newacronym} you should skip this section]
+If you don't intend to use \ics{newacronym} you should skip this section
and not use the above package options.
\end{important}
As mentioned in \sectionref{sec:pkgopts-sec}, the command
\ics{acronymtype} is the name of the glossary in which the acronyms
-should appear. If the \pkgopt{acronym} package option has been used,
+should appear by default. If the \pkgopt{acronym} package option has been used,
this will be \texttt{acronym}, otherwise it will be \texttt{main}.
The acronyms can then be used in exactly the same way as any other
glossary entry. If you want more than one list of acronyms, you must
@@ -4318,7 +5295,8 @@ Since \ics{newacronym} uses \ics{newglossaryentry}, you can use
commands like \ics{gls} and \ics{glsreset} as with any other
glossary entry.
-For example, the following defines the acronym IDN:
+\begin{example}{Defining an Acronym}{ex:newacronym}
+The following defines the acronym IDN:
\begin{verbatim}
\newacronym{idn}{IDN}{identification number}
\end{verbatim}
@@ -4332,6 +5310,7 @@ characters for the shortened form:
Now \verb|\gls{idn}| will produce \qt{identification number
(\textsc{idn})} on \firstuse\ and \qt{\textsc{IDN}} on subsequent
uses.
+\end{example}
If you use any of the package options \pkgopt{smallcaps},
\pkgopt{smaller}, \pkgopt{description} or \pkgopt{footnote}, the
@@ -4362,7 +5341,7 @@ emphasized on subsequent use, do:
\end{verbatim}
(Note that it is for this reason that the \sty{relsize} package is
not automatically loaded when selecting the \pkgopt{smaller} package
-option.)
+option as it may not actually be required.)
There are commands analogous to \ics{glstext} (described in
\sectionref{sec:glslink}) that allow you to access just the short
@@ -4383,7 +5362,18 @@ also analogous upper case variants:
\begin{definition}[\DescribeMacro{\ACRshort}]
\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}
\end{definition}
+There are also plural versions:
+\begin{definition}[\DescribeMacro\acrshortpl]
+\cs{acrshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\Acrshortpl]
+\cs{Acrshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\ACRshortpl]
+\cs{ACRshortpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+Similarly for the long form:
\begin{definition}[\DescribeMacro{\acrlong}]
\cs{acrlong}\oarg{options}\marg{label}\oarg{insert}
\end{definition}
@@ -4397,21 +5387,51 @@ variants:
\begin{definition}[\DescribeMacro{\ACRlong}]
\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}
\end{definition}
+Again there are also plural versions:
+\begin{definition}[\DescribeMacro{\acrlongpl}]
+\cs{acrlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\Acrlongpl}]
+\cs{Acrlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro{\ACRlongpl}]
+\cs{ACRlongpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+And for the full form:
\begin{definition}[\DescribeMacro{\acrfull}]
\cs{acrfull}\oarg{options}\marg{label}\oarg{insert}
\end{definition}
-This is equivalent to:
-\DescribeMacro{\acrfullformat}\cs{acrfullformat}"{"\ics{acrlong}"}{"\ics{acrshort}"}".
This defaults to \meta{long} (\ics{acronymfont}\marg{short})
-regardless of the package options. There are also analogous upper
-case variants:
+regardless of the package options. This format can be changed by
+redefining:
+\begin{definition}[\DescribeMacro\acrfullformat]
+\cs{acrfullformat}\marg{long}\marg{short}
+\end{definition}
+For example, to change \cs{acrfull} to produce
+\cs{acronymfont}\marg{short} (\meta{long})
+you can redefine \cs{acrfullformat} as:
+\begin{verbatim}
+\renewcommand{\acrfullformat}[2]{#2\space(#1)}
+\end{verbatim}
+
+There are also analogous upper case variants:
\begin{definition}[\DescribeMacro{\Acrfull}]
\cs{Acrfull}\oarg{options}\marg{label}\oarg{insert}
\end{definition}
\begin{definition}[\DescribeMacro{\ACRfull}]
\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert}
\end{definition}
+As before there are also plural versions:
+\begin{definition}[\DescribeMacro\acrfullpl]
+\cs{acrfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\Acrfullpl]
+\cs{Acrfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+\begin{definition}[\DescribeMacro\ACRfullpl]
+\cs{ACRfullpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
If you find the above commands too cumbersome to write, you can use
the \pkgopt{shortcuts} package option to activate the shorter
@@ -4493,6 +5513,7 @@ using:
\begin{definition}[\DescribeMacro{\Glsentryfullpl}]
\cs{Glsentryfullpl}\marg{label}
\end{definition}
+(These also use \ics{acrfullformat}.)
\section{Predefined Acronym Styles}
\label{sec:predefinedacrstyles}
@@ -4500,6 +5521,8 @@ using:
Some of the acronym-related package options may be combined. Listed
below are the effects of different combinations. If you use an
invalid combination, you'll get an error message.
+If none of these styles suit your requirements, see
+\sectionref{sec:customacronym} to create your own custom style.
\begin{description}
\item[\pkgopt{description},\pkgopt{footnote}]\ifpdf\mbox{}\par\fi
@@ -4577,6 +5600,9 @@ Note that since the acronym is displayed using \ics{textsc},
the short form, \meta{abbrv}, should be specified in lower case.
\ifpdf(Recall that "\textsc{abc}" produces \textsc{abc} whereas
"\textsc{ABC}" produces \textsc{ABC}.)\fi
+
+See also the \hyperlink{boldsc}{earlier note} regarding combining
+bold and smallcaps.
\end{important}
\item[\pkgopt{smaller}]\ifpdf\mbox{}\par\fi
@@ -4590,7 +5616,7 @@ while subsequent use displays the entry as:
\ics{acronymfont}\marg{abbrv}\meta{insert}
\end{display}
where \ics{acronymfont} is set to
-\verb|\textsmaller{#1}|.\footnote{not that this was change from
+\verb|\textsmaller{#1}|.\footnote{Note that this was changed from
using \ics{smaller} to \ics{textsmaller} as declarations
cause a problem for \ics{makefirstuc}.}
The entries will be sorted according to the short form.
@@ -4620,12 +5646,25 @@ Entries will be sorted according to the short form.
The list of acronyms is just like any other type of glossary and can
be displayed on its own using
-\ics{printglossary}"[type=\acronymtype]" or with all the other
-glossaries using \ics{printglossaries}. However, care must be taken
-to choose a glossary style that's appropriate to your acronym style.
-The different acronym-related package options store different
-information in the \gloskey{name}, \gloskey{description} and
-\gloskey{symbol} keys.
+\begin{alltt}
+\ics{printglossary}[type=\ics{acronymtype}]
+\end{alltt}
+or with all the other
+glossaries using \ics{printglossaries}. (If you use the
+\pkgopt{acronym} package option you can also use
+\begin{alltt}
+\ics{printacronyms}\oarg{options}
+\end{alltt}
+as a synonym for
+\begin{alltt}
+\ics{printglossary}[type=\ics{acronymtype},\meta{options}]
+\end{alltt}
+See \sectionref{sec:pkgopts-acronym}.)
+
+However, care must be taken to choose a glossary style that's
+appropriate to your acronym style. The different acronym-related
+package options store different information in the \gloskey{name},
+\gloskey{description} and \gloskey{symbol} keys.
\Tableref{tab:acronymsettings} lists the package options that govern
the acronym styles and how the information is stored in the keys
@@ -4642,8 +5681,7 @@ and the symbol field will contain the long form. If I then use the
\glostyle{long4col} style, each entry in the list of acronyms will
appear in the form:
\begin{display}
-\ics{acronymfont}\marg{abbrv} \meta{description} \meta{long}
-\meta{location list}
+\ics{acronymfont}\marg{abbrv} \meta{description} \meta{long} \meta{location list}
\end{display}
Alternatively, you can define your own custom style (see
\sectionref{sec:newglossarystyle} for further details).
@@ -4660,15 +5698,15 @@ information is stored}
\gloskey{symbol}\\
\pkgopt{description},\pkgopt{footnote} &
\ics{acronymfont}\marg{abbrv} &
-user supplied &
+custom &
\meta{long}\\
\pkgopt{description},\pkgopt{dua} &
\meta{long} &
-user supplied &
+custom &
\meta{abbrv}\\
\pkgopt{description} &
\ics{acrnameformat}\marg{abbrv}\marg{long} &
-user supplied &
+custom &
\meta{abbrv}\\
\pkgopt{footnote} &
\ics{acronymfont}\marg{abbrv} &
@@ -4717,8 +5755,7 @@ may also be used to set the \gloskey{symbol} or
\cs{SetCustomDisplayStyle}\marg{type}
\end{definition}
This is used to set up the display style for the glossary given by
-\meta{type}. This should typically just use \ics{defglsdisplayfirst}
-and \ics{defglsdisplay}.
+\meta{type}. This should typically just use \ics{defglsentryfmt}.
Once you have redefined \cs{CustomAcronymFields} and
\linebreak\cs{SetCustomDisplayStyle}, you must then switch to this style using
@@ -4733,10 +5770,12 @@ If you omit \cs{SetCustomStyle}, or use it before you redefine
\cs{CustomAcronymFields} and \cs{SetCustomDisplayStyle}, your new
style won't be correctly implemented. You must set up the custom style
before defining new acronyms. The acronyms must be defined using
-\ics{newacronym} not \ics{newglossaryentry}.
+\ics{newacronym} not \ics{newglossaryentry} if you want to use
+acronym styles.
\end{important}
-As an example, suppose I want my acronym on \gls{firstuse} to have the
+\begin{example}{Defining a Custom Acronym Style}{ex:customacrstyle}
+Suppose I want my acronym on \gls{firstuse} to have the
short form in the text and the long form with the description in a
footnote. Suppose also that I want the short form to be put in small
caps in the main body of the document, but I want it in normal
@@ -4758,17 +5797,19 @@ form:
\end{display}
First, I need to redefine \ics{CustomAcronymFields} so that
-\ics{newacronym} will correctly set the \gloskey{name},
+\linebreak\ics{newacronym} will correctly set the \gloskey{name},
\gloskey{text} and \gloskey{plural} keys. I want the long form to be
stored in the \gloskey{name} and the short form to be stored in
\gloskey{text}. In addition, I'm going to set the \gloskey{symbol}
to the short form in upper case so that it will appear in the list
-of acronyms.
+of acronyms. (An alternative approach is to define a custom glossary
+style that uses \ics{glsentryshort} to access the short form. See
+\sectionref{sec:newglossarystyle} for further details).
\begin{verbatim}
\renewcommand*{\CustomAcronymFields}{%
name={\the\glslongtok},%
- symbol={\MakeUppercase{\the\glsshorttok}},%
+ symbol={\MakeTextUppercase{\the\glsshorttok}},%
text={\textsc{\the\glsshorttok}},%
plural={\textsc{\the\glsshorttok}\noexpand\acrpluralsuffix}%
}
@@ -4777,33 +5818,19 @@ of acronyms.
When using \ics{newacronym}, the short and long forms are stored in
the \gloskey{short} and \gloskey{long} keys, and the plural forms
are stored in \gloskey{shortplural} and \gloskey{longplural}.
-So when I use \ics{defglsdisplayfirst}
-and \ics{defglsdisplay}, I can use \ics{glsentrylong} to access
+So when I use \ics{defglsentryfmt}, I can use \ics{glsentrylong} to access
the long form. Recall from \sectionref{sec:glsdisplay}, that the
-optional argument to \ics{defglsdisplayfirst} and \ics{defglsdisplay}
-indicates the glossary type. This is passed to
-\ics{SetCustomDisplayStyle}. The mandatory argument sets up the
-definition of \ics{glsdisplayfirst} and \ics{glsdisplay} for the
-given glossary, where the first argument corresponds to the
-\gloskey{first}, \gloskey{firstplural}, \gloskey{text} or
-\gloskey{plural}, as appropriate, the second argument corresponds to
-the \gloskey{description}, the third corresponds to the
-\gloskey{symbol} and the fourth argument is the inserted text.
-
+optional argument to \ics{defglsentryfmt} indicates the glossary type.
+This is passed to \ics{SetCustomDisplayStyle}.
\begin{verbatim}
\renewcommand*{\SetCustomDisplayStyle}[1]{%
- \defglsdisplayfirst[#1]{##1##4\protect\footnote{%
- \glsentrylong{\glslabel}: ##2%
- }}
- \defglsdisplay[#1]{##1##4}%
+ \defglsentryfmt[#1]{\glsgenentryfmt
+ \ifglsused{\glslabel}% test if entry has been used
+ {}%
+ {\footnote{\glsentrylong{\glslabel}}}}%
}
\end{verbatim}
-Since we have a definition inside a definition, \verb|#1| refers to
-the argument of \ics{SetCustomDisplayStyle}, and \verb|##1|, \ldots,
-\verb|##4|, refer to the arguments of \ics{glsdisplayfirst} and
-\ics{glsdisplay}.
-
Now that I've redefined \ics{CustomAcronymFields} and
\linebreak\ics{SetCustomDisplayStyle}, I can set this style using
\begin{verbatim}
@@ -4820,28 +5847,28 @@ layout of a document written in a markup language}]{css}
{css}{Cascading Style Sheet}
\end{verbatim}
-Note that since I've used the description in the main body of the
-text, I need to switch off the sanitization otherwise any commands
-within the description won't get interpreted. Also I want to use the
-\sty{hyperref} package, but this will cause a problem on \gls{firstuse}
-as I'll get nested hyperlinks, so I need to switch off the
-hyperlinks on \gls{firstuse}. In addition, I want to use a glossary style
-that displays the symbol. Therefore, in my preamble I have:
+If I want to use the \sty{hyperref} package with this document,
+it can cause a problem on \gls{firstuse} as I'll get nested
+hyperlinks, so I need to switch off the hyperlinks on \gls{firstuse}
+via the package option \pkgopt[false]{hyperfirst}. In addition, I
+want to use a glossary style that displays the symbol. Therefore, in
+my preamble I have:
\begin{verbatim}
\usepackage[colorlinks]{hyperref}
\usepackage
- [acronym, % create list of acronyms
- nomain, % don't need main glossary for this example
- style=tree, % need a style that displays the symbol
- hyperfirst=false,% don't hyperlink first use
- sanitize=none % switch off sanitization as description
- % will be used in the main text
+ [acronym, % create list of acronyms
+ nomain, % don't need main glossary for this example
+ style=tree, % need a style that displays the symbol
+ hyperfirst=false% don't hyperlink first use
]{glossaries}
\end{verbatim}
Note that I haven't used the \pkgopt{description} or
\pkgopt{footnote} package options.
+The sample file \samplefile{-custom-acronym} illustrates this
+example.
+\end{example}
\section{Upgrading From the glossary Package}
\label{sec:oldacronym}
@@ -4859,8 +5886,10 @@ provides the command:
\cs{oldacronym}\oarg{label}\marg{abbrv}\marg{long}\marg{key-val list}
\end{definition}
This uses the same syntax as the \sty{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]
+method of defining acronyms. It is equivalent to:
+\begin{display}
+\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}
+\end{display}
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
@@ -4876,8 +5905,11 @@ settings.
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
-\sty{xspace} package.
+\sty{xspace} package, but be aware that there are some issues with
+using \sty{xspace}.\footnotemark
\end{important}
+\footnotetext{See David Carlisle's explanation in
+\url{http://tex.stackexchange.com/questions/86565/drawbacks-of-xspace}}
The \styfmt{glossaries} package doesn't load the \sty{xspace} package
since there are both advantages and disadvantages to using
@@ -4977,15 +6009,19 @@ entry has been used, \meta{true part} will be done, otherwise
\chapter{Glossary Styles}
\label{sec:styles}
-The \styfmt{glossaries} package comes with some pre-defined
-glossary styles. Note that the styles are suited to different
-types of glossaries: some styles ignore the associated
-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. See \tableref{tab:styles} for
-a summary of the available styles. The predefined styles can
+
+Glossaries vary from lists that simply contain a symbol with a terse
+description to lists of terms or phrases with lengthy descriptions.
+Some glossaries may have terms with associated symbols. Some may
+have hierarchical entries. There is therefore no single style
+that fits every type of glossary. The \styfmt{glossaries} package
+comes with a number of pre-defined glossary styles, and you need to
+choose one that best suits your type of glossary. There is a summary
+of available styles in \tableref{tab:styles}. If none of them suit
+your document, you can defined your own style
+(see \sectionref{sec:newglossarystyle}).
+
+The predefined styles can
accommodate numbered level~0 (main) and level~1 entries. See the
package options \pkgopt{entrycounter}, \pkgopt{counterwithin} and
\pkgopt{subentrycounter} described in
@@ -5033,8 +6069,8 @@ be displayed.}
The glossary style can be set using the \gloskey[printglossary]{style} key in the optional
argument to \ics{printglossary} or using the command:
-\begin{definition}[\DescribeMacro{\glossarystyle}]
-\cs{glossarystyle}\marg{style-name}
+\begin{definition}[\DescribeMacro{\setglossarystyle}]
+\cs{setglossarystyle}\marg{style-name}
\end{definition}
Some of the glossary styles may also be set using the \pkgopt{style}
package option, it depends if the package in which they are defined
@@ -5044,7 +6080,7 @@ 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
+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
unless you explicitly load the relevant package.}
@@ -5055,7 +6091,7 @@ 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
+a tabular-like style it's better to use \ics{newline} instead of
\verb|\\|.
Note that if you use the \gloskey[printglossary]{style} key in the
@@ -5068,24 +6104,24 @@ you do
\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
+\verb|style=long|. Likewise, \ics{setglossarystyle} will also
override any previous style definitions, so, again
\begin{verbatim}
\renewcommand*{\glsgroupskip}{}
-\glossarystyle{long}
+\setglossarystyle{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.:
+\ics{setglossarystyle}, e.g.:
\begin{verbatim}
-\glossarystyle{long}
+\setglossarystyle{long}
\renewcommand*{\glsgroupskip}{}
\end{verbatim}
As from version 3.03, you can now use the package option
\pkgopt{nogroupskip} to suppress the gap between groups for the
-default styles.
+default styles instead of redefining \cs{glsgroupskip}.
All the styles except for the three- and four-column styles and the
\glostyle{listdotted} style use the command
@@ -5114,7 +6150,7 @@ these styles will automatically be available unless you use the
\begin{description}
\item[list] The \glostyle{list} style uses the \env{description}
environment. The entry name is placed in the optional argument of
-the \ics{item} command (so it will appear in bold by default). The
+the \ics{item} command (so it will usually appear in bold by default). The
description follows, and then the associated \gls{numberlist} for
that entry. The symbol is ignored. If the entry has child entries,
the description and number list follows (but not the name) for each
@@ -5648,7 +6684,7 @@ For the complete list, see \tableref{tab:mcols}.
Note that \sty{glossary-mcols} is not loaded by \styfmt{glossaries}. If
you want to use any of the multicol styles in that package you need
to load it explicitly with \cs{usepackage} and set the required glossary
-style using \ics{glossarystyle}.
+style using \ics{setglossarystyle}.
\end{important}
The default number of columns is 2, but can be changed by redefining
@@ -5659,7 +6695,7 @@ to the required number. For example, for a three column glossary:
\begin{verbatim}
\usepackage{glossary-mcols}
\renewcommand*{\glsmcols}{3}
-\glossarystyle{mcolindex}
+\setglossarystyle{mcolindex}
\end{verbatim}
\begin{table}[htbp]
@@ -5701,14 +6737,14 @@ glossaries and list of acronyms in a footnote, you can do:
\usepackage{glossary-inline}
\renewcommand*{\glossarysection}[2][]{\textbf{#1}: }
- \glossarystyle{inline}
+ \setglossarystyle{inline}
\end{verbatim}
\begin{important}
Note that you need to include \sty{glossary-inline} with
\cs{usepackage} as it's not automatically included by the
\styfmt{glossaries} package and then set the style using
-\ics{glossarystyle}.
+\ics{setglossarystyle}.
\end{important}
Where you need to include your glossaries as a footnote you can do:
@@ -5747,7 +6783,7 @@ define your own style using:
\cs{newglossarystyle}\marg{name}\marg{definitions}
\end{definition}
where \meta{name} is the name of the new glossary style (to be
-used in \cs{glossarystyle}). The second argument \meta{definitions}
+used in \cs{setglossarystyle}). The second argument \meta{definitions}
needs to redefine all of the following:
\begin{definition}[\DescribeEnv{theglossary}]
@@ -5790,9 +6826,18 @@ via
\begin{definition}[\DescribeMacro{\glsgetgrouptitle}]
\cs{glsgetgrouptitle}\marg{label}
\end{definition}
-This obtains the title as follows: if
+This obtains the title as follows: if \meta{label} consists of a
+single non-active character or \meta{label} is equal to
+\texttt{glssymbols} or \texttt{glsnumbers} and
\cs{}\meta{label}\texttt{groupname} exists, this is taken to be the
-title, otherwise the title is just \meta{label}.
+title, otherwise the title is just \meta{label}. (The \qt{symbols}
+group has the label \texttt{glssymbols}, so the command
+\ics{glssymbolsgroupname} is used, and the \qt{numbers} group has the
+label \texttt{glsnumbers}, so the command \ics{glsnumbersgrouptitle}
+is used.) If you are using \gls{xindy}, \meta{label} may be an
+active character (for example \o), in which case the title will be
+set to just \meta{label}. You can redefine \cs{glsgetgrouptitle} if
+this is unsuitable for your document.
A navigation hypertarget can be created using
\begin{definition}[\DescribeMacro{\glsnavhypertarget}]
@@ -5824,16 +6869,18 @@ produce a blank row.
As from version 3.03, the package option \pkgopt{nogroupskip} can be
used to suppress this default gap for the predefined styles.
-\begin{definition}[\DescribeMacro{\glossaryentryfield}]
-\cs{glossaryentryfield}\marg{label}\marg{formatted name}\marg{description}
-\marg{symbol}\marg{number list}
+\begin{definition}[\DescribeMacro{\glossentry}]
+\cs{glossentry}\marg{label}\marg{number list}
\end{definition}
-This macro indicates what to do for a given glossary entry.
-Note that \meta{formatted name} will always be in the form
-\ics{glsnamefont}\marg{name}. This allows the user to set a given
-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 \ics{newglossaryentry} or \ics{newacronym}.
+This macro indicates what to do for each level~0 glossary entry.
+The entry label is given by \meta{label} and the associated
+\gls{numberlist} is given by \meta{number list}. You can redefine
+\ics{glossentry} to use commands like \ics{glossentryname}\marg{label},
+\ics{glossentrydesc}\marg{label} and \ics{glossentrysymbol}\marg{label}
+to display the name, description and symbol fields, or to access
+other fields, use commands like \ics{glsentryuseri}\marg{label}.
+(See \sectionref{sec:glsnolink} for further details.) You can also
+use the following commands:
\begin{definition}[\DescribeMacro{\glsentryitem}]
\cs{glsentryitem}\marg{label}
@@ -5841,7 +6888,7 @@ was defined via either \ics{newglossaryentry} or \ics{newacronym}.
This macro will increment and display the associated counter for the
main (level~0) entries if the \pkgopt{entrycounter} or
\pkgopt{counterwithin} package options have been used. This macro
-is typically called by \cs{glossaryentryfield} before \cs{glstarget}.
+is typically called by \cs{glossentry} before \cs{glstarget}.
The format of the counter is controlled by the macro
\begin{definition}[\DescribeMacro{\glsentrycounterlabel}]
\cs{glsentrycounterlabel}
@@ -5850,7 +6897,7 @@ The format of the counter is controlled by the macro
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
+\cs{glossentry} to set the appropriate target. This
is done using
\begin{definition}[\DescribeMacro{\glstarget}]
\cs{glstarget}\marg{label}\marg{text}
@@ -5860,15 +6907,15 @@ don't need to worry about whether the \sty{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:
+For example, the \glostyle{list} style defines \cs{glossentry} as follows:
\begin{verbatim}
-\renewcommand*{\glossaryentryfield}[5]{%
-\item[\glsentryitem{##1}\glstarget{##1}{##2}]
- ##3\glspostdescription \space ##5}
+ \renewcommand*{\glossentry}[2]{%
+ \item[\glsentryitem{##1}%
+ \glstarget{##1}{\glossentryname{##1}}]
+ \glossentrydesc{##1}\glspostdescription\space ##2}
\end{verbatim}
-Note also that \meta{number list} will always be of the form\\
+Note also that \meta{number list} will always be of the form
\begin{definition}
\ics{glossaryentrynumbers}\{\cs{relax}\\
\ics{setentrycounter}\oarg{Hprefix}\marg{counter name}\meta{format cmd}\marg{number(s)}\}
@@ -5889,22 +6936,21 @@ Therefore, when you define a new glossary style, you don't need
to worry about whether the user has specified the
\pkgopt{nonumberlist} package option.
-\begin{definition}[\DescribeMacro{\glossarysubentryfield}]
-\cs{glossarysubentryfield}\marg{level}\marg{label}\marg{formatted name}
-\marg{description}\marg{symbol}\marg{number list}
+\begin{definition}[\DescribeMacro{\subglossentry}]
+\cs{subglossentry}\marg{level}\marg{label}\marg{number list}
\end{definition}
-This is new to version 1.17, and is used to display sub-entries.
+This is used to display sub-entries.
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.
+\ics{glossentry} described above.
\begin{definition}[\DescribeMacro{\glssubentryitem}]
\cs{glssubentryitem}\marg{label}
\end{definition}
This macro will increment and display the associated counter for the
-level~1 entries if the \pkgopt{subentrycounter} package options have
-been used. This macro is typically called by \cs{glossarysubentryfield}
+level~1 entries if the \pkgopt{subentrycounter} package option has
+been used. This macro is typically called by \cs{subglossentry}
before \ics{glstarget}. The format of the counter is controlled by
the macro
\begin{definition}[\DescribeMacro{\glssubentrycounterlabel}]
@@ -5923,8 +6969,7 @@ For further details of these commands, see \ifpdf
section~\ref*{sec:code:printglos} \fi \qt{Displaying the glossary}
in the documented code (\texttt{glossaries-code.pdf}).
-\section{Example: creating a completely new style}
-\label{sec:exnewstyle}
+\begin{example}{Creating a completely new style}{sec:exnewstyle}
If you want a completely new style, you will need to redefine all
of the commands and the environment listed above.
@@ -5952,16 +6997,16 @@ at the end. Then you can create this new glossary style, called, say,
\renewcommand*{\glsgroupheading}[1]{}%
\renewcommand*{\glsgroupskip}{}%
% set how each entry should appear:
- \renewcommand*{\glossaryentryfield}[5]{%
+ \renewcommand*{\glossentry}[2]{%
\item % bullet point
- \glstarget{##1}{##2}% the entry name
- \space (##4)% the symbol in brackets
- \space ##3% the description
- \space [##5]% the number list in square brackets
+ \glstarget{##1}{\glossentryname{##1}}% the entry name
+ \space (\glossentrysymbol{##1})% the symbol in brackets
+ \space \glossentrydesc{##1}% the description
+ \space [##2]% the number list in square brackets
}%
% set how sub-entries appear:
- \renewcommand*{\glossarysubentryfield}[6]{%
- \glossaryentryfield{##2}{##3}{##4}{##5}{##6}}%
+ \renewcommand*{\subglossentry}[3]{%
+ \glossentry{##2}{##3}}%
}
\end{verbatim}
Note that this style creates a flat glossary, where sub-entries
@@ -5970,12 +7015,35 @@ It also hasn't used \ics{glsentryitem} or \ics{glssubentryitem} so
it won't be affected by the \pkgopt{entrycounter},
\pkgopt{counterwithin} or \pkgopt{subentrycounter} package options.
-\section{Example: creating a new glossary style based on an
-existing style}
-\label{sec:exadaptstyle}
+Variations:
+\begin{itemize}
+\item You might want the entry name to be capitalised, in
+which case use \ics{Glossentryname} instead of \ics{glossentryname}.
+
+\item You might want to check if the symbol hasn't been set and omit
+the parentheses if the symbol is absent. In this case you can use
+\ics{ifglshassymbol} (see \sectionref{sec:utilities}):
+\begin{verbatim}
+ \renewcommand*{\glossentry}[2]{%
+ \item % bullet point
+ \glstarget{##1}{\glossentryname{##1}}% the entry name
+ \ifglshassymbol{##1}% check if symbol exists
+ {%
+ \space (\glossentrysymbol{##1})% the symbol in brackets
+ }%
+ {}% no symbol so do nothing
+ \space \glossentrydesc{##1}% the description
+ \space [##2]% the number list in square brackets
+ }%
+\end{verbatim}
+\end{itemize}
+\end{example}
+
+\begin{example}{Creating a new glossary style based on an
+existing style}{sec:exadaptstyle}
If you want to define a new style that is a slightly modified
-version of an existing style, you can use \ics{glossarystyle}
+version of an existing style, you can use \ics{setglossarystyle}
within the second argument of \ics{newglossarystyle} followed by
whatever alterations you require. For example, suppose you want
a style like the \glostyle{list} style but you don't want the extra
@@ -5984,21 +7052,21 @@ can create a new glossary style called, say, \texttt{mylist} as
follows:
\begin{verbatim}
\newglossarystyle{mylist}{%
-\glossarystyle{list}% base this style on the list style
+\setglossarystyle{list}% base this style on the list style
\renewcommand{\glsgroupskip}{}% make nothing happen
% between groups
}
\end{verbatim}
+(In this case, you can actually achieve the same effect using the
+\glostyle{list} style in combination with the package option
+\pkgopt{nogroupskip}.)
+\end{example}
-\section{Example: creating a glossary style that uses the
+\begin{example}{Example: creating a glossary style that uses the
\texorpdfstring{\gloskey{user1}}{user1}, \ldots,
-\texorpdfstring{\gloskey{user6}}{user6} keys}
-\label{sec:exuserstyle}
+\texorpdfstring{\gloskey{user6}}{user6} keys}{sec:exuserstyle}
-Since \ics{glossaryentryfield} and \ics{glossarysubentryfield}
-provide the label for the entry, it's also possible to access
-the values of the generic user keys, such as \gloskey{user1}. For
-example, suppose each entry not only has an associated symbol,
+Suppose each entry not only has an associated symbol,
but also units (stored in \gloskey{user1}) and dimension
(stored in \gloskey{user2}). Then you can define a glossary style
that displays each entry in a \env{longtable} as follows:
@@ -6016,31 +7084,32 @@ that displays each entry in a \env{longtable} as follows:
% No heading between groups:
\renewcommand*{\glsgroupheading}[1]{}%
% Main (level 0) entries displayed in a row optionally numbered:
- \renewcommand*{\glossaryentryfield}[5]{%
+ \renewcommand*{\glossentry}[2]{%
\glsentryitem{##1}% Entry number if required
- \glstarget{##1}{##2}% Name
- & ##3% Description
- & ##4% Symbol
+ \glstarget{##1}{\glossentryname{##1}}% Name
+ & \glossentrydesc{##1}% Description
+ & \glossentrysymbol{##1}% Symbol
& \glsentryuseri{##1}% Units
& \glsentryuserii{##1}% Dimensions
- & ##5% Page list
- \\% end of row
+ & ##2% Page list
+ \tabularnewline % end of row
}%
% Similarly for sub-entries (no sub-entry numbers):
- \renewcommand*{\glossarysubentryfield}[6]{%
+ \renewcommand*{\subglossentry}[3]{%
% ignoring first argument (sub-level)
- \glstarget{##2}{##3}% Name
- & ##4% Description
- & ##5% Symbol
+ \glstarget{##2}{\glossentryname{##2}}% Name
+ & \glossentrydesc{##2}% Description
+ & \glossentrysymbol{##2}% Symbol
& \glsentryuseri{##2}% Units
& \glsentryuserii{##2}% Dimensions
- & ##6% Page list
- \\% end of row
+ & ##3% Page list
+ \tabularnewline % end of row
}%
% Nothing between groups:
\renewcommand*{\glsgroupskip}{}%
}
\end{verbatim}
+\end{example}
\chapter{Utilities}
\label{sec:utilities}
@@ -6090,9 +7159,28 @@ part}}
\end{definition}
This checks if the glossary entry given by \meta{label} exists. If it
does \meta{true part} is performed, otherwise \meta{false part}.
+(Note that \cs{ifglsentryexists} will always be true after the
+containing glossary has been displayed via \ics{printglossary}
+or \ics{printglossaries} even if the entry is explicitly defined
+later in the document. This is because the entry has to be defined
+before it can be displayed in the glossary, see \sectionref{sec:techissues} for
+further details.)
+
+\begin{definition}[\DescribeMacro{\glsdoifexists}]
+\cs{glsdoifexists}\marg{label}\marg{code}
+\end{definition}
+Does \meta{code} if the entry given by \meta{label} exists. If it
+doesn't exist, an error is generated. (This command uses
+\cs{ifglsentryexists}.)
+
+\begin{definition}[\DescribeMacro{\glsdoifnoexists}]
+\cs{glsdoifnoexists}\marg{label}\marg{code}
+\end{definition}
+Does the reverse of \cs{glsdoifexists}. (This command uses
+\cs{ifglsentryexists}.)
\begin{definition}[\DescribeMacro{\ifglsused}]
-\cs{ifglsentryexists}{\meta{label}}{\meta{true part}}{\meta{false
+\cs{ifglsused}{\meta{label}}{\meta{true part}}{\meta{false
part}}
\end{definition}
See \sectionref{sec:glsunset}.
@@ -6113,6 +7201,270 @@ This checks if the glossary entry given by \meta{label} has a parent
entry. If it does, \meta{true part} is performed, otherwise
\meta{false part}.
+\begin{definition}[\DescribeMacro{\ifglshassymbol}]
+\cs{ifglshassymbol}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the glossary entry given by \meta{label} has had the
+\gloskey{symbol} field set. If it has, \meta{true part} is performed,
+otherwise \meta{false part}.
+
+\begin{definition}[\DescribeMacro{\ifglshaslong}]
+\cs{ifglshaslong}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the glossary entry given by \meta{label} has had the
+\gloskey{long} field set. If it has, \meta{true part} is performed,
+otherwise \meta{false part}. This should be true for any entry that
+has been defined via \ics{newacronym}.
+
+\begin{definition}[\DescribeMacro{\ifglshasshort}]
+\cs{ifglshasshort}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the glossary entry given by \meta{label} has had the
+\gloskey{short} field set. If it has, \meta{true part} is performed,
+otherwise \meta{false part}. This should be true for any entry that
+has been defined via \ics{newacronym}.
+
+\begin{definition}[\DescribeMacro{\ifglshasdesc}]
+\cs{ifglshasdesc}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the \gloskey{description} field is non-empty for
+the entry given by \meta{label}. If it has, \meta{true part} is
+performed, otherwise \meta{false part}. Compare with:
+\begin{definition}[\DescribeMacro{\ifglsdescsuppressed}]
+\cs{ifglsdescsuppressed}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+This checks if the \gloskey{description} field has been set to just
+\ics{nopostdesc} for the entry given by \meta{label}. If it has,
+\meta{true part} is performed, otherwise \meta{false part}.
+
+\chapter{Prefixes or Determiners}\label{sec:prefix}
+The \sty{glossaries-prefix} package provides
+additional keys that can be used as prefixes. For example, if you
+want to specify determiners (such
+as \qt{a}, \qt{an} or \qt{the}). The \styfmt{glossaries-prefix}
+package automatically loads the \styfmt{glossaries} package and has
+the same package options.
+
+The extra keys for \ics{newglossaryentry} are as follows:
+\begin{description}
+\item[\gloskey{prefix}] The prefix associated with the
+\gloskey{text} key. This defaults to nothing.
+
+\item[\gloskey{prefixplural}] The prefix associated with the
+\gloskey{plural} key. This defaults to nothing.
+
+\item[\gloskey{prefixfirst}] The prefix associated with the
+\gloskey{first} key. If omitted, this defaults to the value of the
+\gloskey{prefix} key.
+
+\item[\gloskey{prefixfirstplural}] The prefix associated with the
+\gloskey{firstplural} key. If omitted, this defaults to the value of
+the \gloskey{prefixplural} key.
+\end{description}
+
+\begin{example}{Defining Determiners}{ex:determiners}
+Here's the start of my example document:
+\begin{verbatim}
+documentclass{article}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage[toc,acronym]{glossaries-prefix}
+\end{verbatim}
+Note that I've simply replaced \styfmt{glossaries} from previous
+sample documents with \styfmt{glossaries-prefix}. Now for a sample
+definition\footnote{Single letter words, such as \qt{a} and \qt{I}
+should typically not appear at the end of a line, hence the
+non-breakable space after \qt{a} in the \gloskey{prefix} field.}:
+\begin{verbatim}
+\newglossaryentry{sample}{name={sample},%
+ description={an example},%
+ prefix={a~},%
+ prefixplural={the\space}%
+}
+\end{verbatim}
+Note that I've had to explicitly insert a~space after the prefix.
+This allows for the possibility of prefixes that shouldn't have a~space,
+such as:
+\begin{verbatim}
+\newglossaryentry{oeil}{name={oeil},
+ plural={yeux},
+ description={eye},
+ prefix={l'},
+ prefixplural={les\space}}
+\end{verbatim}
+Where a space is required at the end of the prefix, you must use
+a~spacing command, such as \cs{space}, \verb*|\ | (backslash space) or
+\verb|~| due to the automatic spacing trimming performed in
+\meta{key}=\meta{value} options.
+
+The prefixes can also be used with acronyms. For example:
+\begin{verbatim}
+\newacronym
+ [%
+ prefix={an\space},prefixfirst={a~}%
+ ]{svm}{SVM}{support vector machine}
+\end{verbatim}
+\end{example}
+
+The \sty{glossaries-prefix} package provides convenient commands to
+use these prefixes with commands such as \ics{gls}. Note that the
+prefix is not considered part of the \gls{linktext}, so it's not
+included in the hyperlink (where hyperlinks are enabled).
+\begin{definition}[\DescribeMacro\pgls]
+\cs{pgls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This is prepends the value of the \gloskey{prefix} key (or
+\gloskey{prefixfirst} key, on \gls{firstuse}) in front of
+\cs{gls}\oarg{options}\marg{label}\oarg{insert}.
+
+\begin{definition}[\DescribeMacro\Pgls]
+\cs{Pgls}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+If the \gloskey{prefix} key (or \gloskey{prefixfirst}, on
+\gls*{firstuse}) has been set, this displays the value of that key
+with the first letter converted to upper case followed by
+\cs{gls}\oarg{options}\marg{label}\oarg{insert}. If that key hasn't
+been set, this is equivalent to
+\ics{Gls}\oarg{options}\marg{label}\oarg{insert}.
+
+\begin{definition}[\DescribeMacro\PGLS]
+\cs{PGLS}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+As \cs{pgls} but converts the prefix to upper case and uses
+\ics{GLS} instead of \cs{gls}.
+
+\begin{definition}[\DescribeMacro\pglspl]
+\cs{pglspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+This is prepends the value of the \gloskey{prefixplural} key (or
+\gloskey{prefixfirstplural} key, on \gls{firstuse}) in front of
+\cs{glspl}\oarg{options}\marg{label}\oarg{insert}.
+
+\begin{definition}[\DescribeMacro\Pglspl]
+\cs{Pglspl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+If the \gloskey{prefixplural} key (or \gloskey{prefixfirstplural}, on
+\gls*{firstuse}) has been set, this displays the value of that key
+with the first letter converted to upper case followed by
+\cs{glspl}\oarg{options}\marg{label}\oarg{insert}. If that key hasn't
+been set, this is equivalent to
+\ics{Glspl}\oarg{options}\marg{label}\oarg{insert}.
+
+\begin{definition}[\DescribeMacro\PGLSpl]
+\cs{PGLSpl}\oarg{options}\marg{label}\oarg{insert}
+\end{definition}
+As \cs{pglspl} but converts the prefix to upper case and uses
+\ics{GLSpl} instead of \cs{glspl}.
+
+\begin{example}{Using Prefixes}{ex:prefixes}
+Continuing from Example~\ref{ex:determiners}, now that I've defined
+my entries, I~can use them in the text via the above commands:
+\begin{verbatim}
+First use: \pgls{svm}. Next use: \pgls{svm}.
+Singular: \pgls{sample}, \pgls{oeil}.
+Plural: \pglspl{sample}, \pglspl{oeil}.
+\end{verbatim}
+which produces:
+\begin{quote}
+First use: a~support vector machine (SVM). Next
+use: an SVM.
+Singular: a~sample, l'oeil. Plural: the samples, les yeux.
+\end{quote}
+For a complete document, see \samplefile{-prefix}.
+\end{example}
+
+This package also provides the following commands:
+\begin{definition}[\DescribeMacro\ifglshasprefix]
+\cs{ifglshasprefix}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+Does \meta{true part} if the entry identified by \meta{label} has a
+non-empty value for the \gloskey{prefix} key.
+
+This package also provides the following commands:
+\begin{definition}[\DescribeMacro\ifglshasprefixplural]
+\cs{ifglshasprefixplural}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+Does \meta{true part} if the entry identified by \meta{label} has a
+non-empty value for the \gloskey{prefixplural} key.
+
+\begin{definition}[\DescribeMacro\ifglshasprefixfirst]
+\cs{ifglshasprefixfirst}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+Does \meta{true part} if the entry identified by \meta{label} has a
+non-empty value for the \gloskey{prefixfirst} key.
+
+\DescribeMacro\ifglshasprefixfirstplural
+\begin{definition}
+\cs{ifglshasprefixfirstplural}\marg{label}\marg{true part}\marg{false part}
+\end{definition}
+Does \meta{true part} if the entry identified by \meta{label} has a
+non-empty value for the \gloskey{prefixfirstplural} key.
+
+\begin{definition}[\DescribeMacro\glsentryprefix]
+\cs{glsentryprefix}\marg{label}
+\end{definition}
+Displays the value of the \gloskey{prefix} key for the entry given
+by \meta{label}. (No check is performed to determine if the entry
+exists.)
+
+\begin{definition}[\DescribeMacro\glsentryprefixfirst]
+\cs{glsentryprefixfirst}\marg{label}
+\end{definition}
+Displays the value of the \gloskey{prefixfirst} key for the entry given
+by \meta{label}. (No check is performed to determine if the entry
+exists.)
+
+\begin{definition}[\DescribeMacro\glsentryprefixplural]
+\cs{glsentryprefixplural}\marg{label}
+\end{definition}
+Displays the value of the \gloskey{prefixplural} key for the entry given
+by \meta{label}. (No check is performed to determine if the entry
+exists.)
+
+\DescribeMacro\glsentryprefixfirstplural
+\begin{definition}
+\cs{glsentryprefixfirstplural}\marg{label}
+\end{definition}
+Displays the value of the \gloskey{prefixfirstplural} key for the entry given
+by \meta{label}. (No check is performed to determine if the entry
+exists.)
+
+There are also variants that convert the first letter to upper
+case\footnote{The earlier caveats about initial non-Latin characters
+apply.}:
+\begin{definition}[\DescribeMacro\Glsentryprefix]
+\cs{Glsentryprefix}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro\Glsentryprefixfirst]
+\cs{Glsentryprefixfirst}\marg{label}
+\end{definition}
+\begin{definition}[\DescribeMacro\Glsentryprefixplural]
+\cs{Glsentryprefixplural}\marg{label}
+\end{definition}
+
+\pagebreak
+\DescribeMacro\Glsentryprefixfirstplural
+\begin{definition}
+\cs{Glsentryprefixfirstplural}\marg{label}
+\end{definition}
+
+\begin{example}{Adding Determiner to Glossary Style}{ex:plist}
+You can use the above commands to define a new glossary style that
+uses the determiner. For example, the following style is a slight
+modification of the \glostyle{list} style that inserts the prefix
+before the name:
+\begin{verbatim}
+\newglossarystyle{plist}{%
+ \setglossarystyle{list}%
+ \renewcommand*{\glossentry}[2]{%
+ \item[\glsentryitem{##1}%
+ \Glsentryprefix{##1}%
+ \glstarget{##1}{\glossentryname{##1}}]
+ \glossentrydesc{##1}\glspostdescription\space ##2}%
+}
+\end{verbatim}
+\end{example}
+
\chapter{Accessibility Support}\label{sec:accsupp}
Limited accessibility support is provided by the accompanying
\sty{glossaries-accsupp} package, but note that this package is
@@ -6186,7 +7538,8 @@ should be located in the \texttt{samples} subdirectory (folder)
of the \styfmt{glossaries} documentation directory. The location
varies according to your operating system and \TeX\ installation.
For example, on my Linux partition it can be found in
-\texttt{/usr/local/texlive/2008/texmf-dist\linebreak/doc/latex/glossaries/}.
+\texttt{\slash usr\slash local\slash texlive\slash 2013\slash
+texmf-dist\slash doc\slash latex\slash glossaries/}.
Further information on debugging \LaTeX\ code is available at
\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/minexample/}.
@@ -6195,16 +7548,28 @@ queries, consult the \styfmt{glossaries} FAQ at
\url{http://www.dickimaw-books.com/faqs/glossariesfaq.html}. If that
doesn't help, try posting your query to somewhere like the
comp.text.tex newsgroup, the \LaTeX\ Community Forum
-(\url{http://www.latex-community.org/}) or Stack Exchange
-(\url{http://tex.stackexchange.com/}). I read all those three places
-and respond to queries there far quicker than to email messages (my
-inbox is always very cluttered).
+(\url{http://www.latex-community.org/}) or \TeX\ on StackExchange
+(\url{http://tex.stackexchange.com/}).
Bug reports can be submitted at
\url{http://www.dickimaw-books.com/bug-report.html}.
\begin{enumerate}
\item \textbf{Q.} I get the error message:
\begin{verbatim}
+! Undefined control sequence.
+\in@ #1#2->\begingroup \def \in@@
+\end{verbatim}
+
+\textbf{A.} This error can occur if you have a fragile command in
+one of your entry definitions.
+In most cases using \cs{glsnoexpandfields} before defining your
+entry should fix this, but there are still a few fragile commands
+that will still cause this error even with \cs{glsnoexpandfields}.
+If this is the case put \cs{protect} in front of the fragile
+command.
+
+\item \textbf{Q.} I get the error message:
+\begin{verbatim}
Missing \begin{document}
\end{verbatim}
@@ -6307,48 +7672,10 @@ English, French, German, Irish, Italian, Hungarian, Polish, Serbian and
Spanish. If you want to add another language, send me the
translations, and I'll add them to the next version.
-If you are using one of the above languages, but the text hasn't been
-translated, try adding the \sty{translator} package with the
-required languages explicitly (before you load the \styfmt{glossaries}
-package). For example:
-\begin{verbatim}
-\usepackage[ngerman]{babel}
-\usepackage[ngerman]{translator}
-\usepackage{glossaries}
-\end{verbatim}
-Alternatively, you can add the language as a global option
-to the class file. Check the \styfmt{translator} package documentation
-for further details.
-
-\item \textbf{Q.} My acronyms contain strange characters when I use commands
-like \ics{acrlong}.
-
-\textbf{A.} Switch off the sanitization:
-\begin{verbatim}
-\usepackage[sanitize=none]{glossaries}
-\end{verbatim}
-and protect fragile commands.
-
-\item \textbf{Q.} Weird characters appear when I use
-\ics{glsentryname} or \ics{glsname}.
-
-\textbf{A.} Either use \ics{glsentrytext} or \ics{glstext},
-respectively, or switch off the sanitization for the \gloskey{name}
-key:
-\begin{verbatim}
-\usepackage[sanitize={name=false}]{glossaries}
-\end{verbatim}
-and protect fragile commands.
-
-\item \textbf{Q.} Weird characters appear when I try to display an
-entry's description.
-
-\textbf{A.} Switch off the sanitization for the \gloskey{description}
-key:
-\begin{verbatim}
-\usepackage[sanitize={description=false}]{glossaries}
-\end{verbatim}
-and protect fragile commands.
+If you are using one of the above languages, but the text hasn't
+been translated, try using the \styfmt{glossaries} package option
+\pkgopt[babel]{translate}. Also, try adding the language as a
+global option to the class file.
\item \textbf{Q.} My glossaries haven't appeared.
@@ -6375,6 +7702,13 @@ second \LaTeX\ run, followed by another \LaTeX\ run.
Check the log files (\filetype{.log}, \filetype{.glg} etc) for any
warnings.
+\item \textbf{Q.} Why is glossaries creating an empty \filetype{.glo} file?
+
+\textbf{A.} Because you haven't used any entries in the
+\texttt{main} glossary via commands such as \ics{gls}.
+If you don't want to use this glossary, you can suppress its
+creation via the package option \pkgopt{nomain}.
+
\item \textbf{Q.} It is possible to change the rules used to sort
the glossary entries?
@@ -6410,8 +7744,6 @@ or
\end{enumerate}
-
-\clearpage\phantomsection
-\addcontentsline{toc}{chapter}{Index}\PrintIndex
+\PrintIndex
\end{document}