diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex | 1947 |
1 files changed, 1947 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex new file mode 100644 index 00000000000..9ede69d65e0 --- /dev/null +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex @@ -0,0 +1,1947 @@ +\documentclass[a4paper]{ltxdoc} +\usepackage{ifthen} +\usepackage{alltt} +\usepackage[colorlinks, + bookmarks, + hyperindex=false, + pdfauthor={Nicola L.C. Talbot}, + pdftitle={glossaries.sty: LaTeX2e Package to Assist Generating Glossaries}, + pdfkeywords={LaTeX,package,glossary,acronyms}]{hyperref} + + %hyperindex conflicts with doc + %(end up with |usage|hyperpage in indexentry) + %This unfortunately means that the changes section doesn't + %have active links, but at least it will keep makeindex happy. + +\usepackage{creatdtx} +\ifmakedtx{ +\renewcommand{\usage}[1]{\textit{\hyperpage{#1}}} +\renewcommand{\main}[1]{\hyperpage{#1}} +\newcommand{\see}[2]{\emph{see} #1} +\makeatletter +\def\index@prologue{\section*{Index}} +\makeatother +\RecordChanges +\PageIndex +\CheckSum{4357} +\CodelineNumbered +\newcommand*{\termdef}[1]{\emph{#1}\iterm{#1}} +\newcommand*{\term}[1]{#1\iterm{#1}} +\newcommand*{\iterm}[1]{\index{#1|main}} +\newcommand{\dq}[1]{``#1''} +} +{ +\usepackage{html} +\usepackage{makeidx} +\renewcommand{\LaTeX}{LaTeX} +\renewcommand{\LaTeXe}{LaTeX2e} +\newcommand*{\termdef}[1]{\emph{#1}\index{#1}} +\newcommand*{\term}[1]{#1\index{#1}} +\newcommand*{\iterm}[1]{\index{#1}} +\newcommand{\dq}[1]{"#1"} +} + + +\ifmakedtx{ +\newcommand*{\istkey}[1]{\texttt{#1}\index{makeindex=\texttt{makeindex}>#1=\texttt{#1}|hyperpage}} +\newcommand*{\ics}[1]{\texttt{\char`\\#1}\SpecialMainIndex{#1}} +\newcommand*{\appname}[1]{\texttt{#1}\index{#1=\texttt{#1}|hyperpage}} +\newcommand*{\mkidxspch}{\index{makeindex=\texttt{makeindex}>special characters|hyperpage}} +\newcommand*{\igloskey}[2][newglossaryentry]{\index{#1 options=\cs{#1} options>#2=\textsf{#2}|hyperpage}} +\newcommand*{\gloskey}[2][newglossaryentry]{\textsf{#2}\igloskey[#1]{#2}} +\newcommand*{\ipkgopt}[2][]{% +\ifthenelse{\equal{#1}{}}{% +\index{package options>#2=\textsf{#2}|hyperpage}}{% +\index{package options>#2=\textsf{#2}>#1=\textsf{#1}|hyperpage}}} +\newcommand*{\pkgopt}[2][]{% +\ifthenelse{\equal{#1}{}}{% +\textsf{#2}\index{package options>#2=\textsf{#2}|hyperpage}}{% +\textsf{#2=#1}\index{package options>#2=\textsf{#2}>#1=\textsf{#1}|hyperpage}}} +\newcommand*{\pkgoptval}[2]{\textsf{#1}\index{package options>#2=\textsf{#2}>#1=\textsf{#1}|hyperpage}} +\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles>#1|hyperpage}} +\newcommand*{\filetype}[1]{\texttt{#1}\index{file types>#1|hyperpage}} +\newcommand*{\sty}[1]{\textsf{#1}} +\newcommand*{\isty}[1]{\sty{#1}\index{#1 package=\sty{#1} package|hyperpage}} +\newcommand*{\envname}[1]{\textsf{#1}} +} +{ +\newcommand{\istkey}[1]{\texttt{#1}\index{makeindex key!#1}} +\newcommand{\ics}[1]{\texttt{\char`\\#1}\index{#1@\cs{#1}}} +\html{\newcommand{\SpecialMainIndex}[1]{\index{#1@\cs{#1}}}} +\newcommand{\appname}[1]{\texttt{#1}\index{#1@\texttt{#1}}} +\newcommand*{\mkidxspch}{\index{makeindex@\texttt{makeindex}!special characters|hyperpage}} +\newcommand{\gloskey}[2][newglossaryentry]{\texttt{#2}\index{#1 keys@\cs{#1} keys!#2}} +\newcommand{\ipkgopt}[2][]{% +\ifthenelse{\equal{#1}{}}{% +\index{package options!#2}}{% +\index{package options!#2!#1}}} +\newcommand{\pkgopt}[2][]{% +\ifthenelse{\equal{#1}{}}{% +\texttt{#2}\index{package options!#2}}{% +\texttt{#2=#1}\index{package options!#2!#1}}} +\newcommand{\pkgoptval}[2]{\texttt{#1}\index{package options!#2!#1}} +\newcommand{\glostyle}[1]{\texttt{#1}\index{glossary styles!#1}} +\newcommand{\filetype}[1]{\texttt{#1}\index{file types!#1}} +\newcommand{\sty}[1]{\texttt{#1}} +\newcommand{\isty}[1]{\sty{#1}\index{#1@\sty{#1}}} +\newcommand{\envname}[1]{\texttt{#1}} +\newcommand{\toTop}{\mbox{}\par\htmlref{Top}{top}} +} + +\begin{document}\ifmakedtx{}{\label{top}} +\MakeShortVerb{"} +\DeleteShortVerb{\|} + + \title{glossaries.sty v 1.11: \LaTeXe\ Package to Assist Generating Glossaries} + \author{Nicola L.C. Talbot\\[10pt] +School of Computing Sciences\\ +University of East Anglia\\ +Norwich. Norfolk\\ +NR4 7TJ. United Kingdom.\\ +\url{http://theoval.cmp.uea.ac.uk/~nlct/}} + + \date{2nd March 2008} + \maketitle +\tableofcontents + + \section{Introduction} + + \changes{1.0}{2007 May 16}{Initial version} +The \sty{glossaries} package is provided to assist generating +glossaries. It has a certain amount of flexibility, allowing the user +to customize the format of the glossary and define multiple glossaries. +It also supports acronyms and glossary styles that include +symbols (in addition to a name and description) for glossary +entries. There is provision for loading a database of glossary terms +where only those terms used in the text are added to the glossary. +This package replaces the \isty{glossary} package which is now +obsolete. + +As from version 1.08, the \sty{glossaries} package now has +limited multi-lingual support, thanks to all the people who have sent +me the relevant translations either via email or via comp.text.tex. +However you must load \isty{babel} \emph{before} +\sty{glossaries} to enable this. \ifmakedtx{(See \autoref{sec:predefinednames} for the +predefined names used by the \sty{glossaries} package.)}{} +As from version 1.1, the \sty{glossaries} package also supports +Till~Tantau's \isty{translator} package provided it is loaded +before the \sty{glossaries} package. This makes it easier to change +the default translations or add new dictionaries. +If you don't want to use the predefined translations, you can use the +package option \pkgopt[false]{translate} and supply your own translations. + +This documentation is structured as follows: \ifmakedtx{\autoref{sec:quick}}{\htmlref{{A Quick Guide For The Impatient}}{sec:quick}} is for +people who want a few quick pointers of how to get started, +without having to read through lengthy descriptions, +\ifmakedtx{\autoref{sec:overview}}{and \htmlref{Overview}{sec:overview}} gives an overview of available commands +and their syntax\ifmakedtx{, \autoref{sec:code} contains the documented +source code for those who want to know more about how the +package works, and how to do more complicated things, such as +changing the way glossary entries appear}{}.\ifmakedtx{}{\toTop} + +\subsection{Generating the associated glossary files} +\label{sec:makeglossaries} + +The \sty{glossaries} package comes with the Perl script +\appname{makeglossaries} which will run \appname{makeindex} on +all the glossary files using a customized \appname{makeindex} +\filetype{.ist} style file (which is created by \ics{makeglossaries}). +The relevant extensions are obtained from the +auxiliary file, so you should only pass the basename as the +argument. For example, if your document is called +\texttt{myfile.tex}, do: +\begin{verbatim} +latex myfile +makeglossaries myfile +latex myfile +\end{verbatim} +You may need to explicitly load \appname{makeglossaries} into +Perl: +\begin{verbatim} +perl makeglossaries myfile +\end{verbatim} +There is a batch file called \texttt{makeglossaries.bat} which +does this for Windows users. + +If you don't have Perl installed, you will have to run +\appname{makeindex} for each glossary type you have defined. +For example, if you have used the \pkgopt{acronym} package option +then you will have both a main glossary as well as a list of acronyms, so you +will need to do (assuming your document is called \texttt{myfile.tex}): +\begin{verbatim} +makeindex -s myfile.ist -t myfile.glg -o myfile.gls myfile.glo +makeindex -s myfile.ist -t myfile.alg -o myfile.acr myfile.acn +\end{verbatim} +This requires remembering all extensions for each of the glossaries +defined in your document, so where possible you should use +\appname{makeglossaries} instead to reduce the possibility of error. +Don't pass all the glossary files in a single call to +\appname{makeindex} or it will merge all your glossaries into a +single glossary. + +If any problems occur, remember to check the transcript files +(e.g.\ \filetype{.glg} or \filetype{.alg}) for messages.\ifmakedtx{}{\toTop} + +\subsection{Troubleshooting} + +The glossaries package comes with a minimal file called +\texttt{minimalgls.tex} which can be used for testing. This +should be located in \texttt{texmf/doc/latex/glossaries/samples/}. Further +information on debugging \LaTeX\ code is available at +\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/minexample/}. + +There is a list of frequently asked questions for the +\sty{glossaries} package available at +\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/packages/faq/glossariesfaq.html}.\ifmakedtx{}{\toTop} + +\section{A Quick Guide For The Impatient} +\label{sec:quick} + +This section is for people who want a few quick pointers +of how to get started, without having to read through +lengthy descriptions. + +\begin{enumerate} +\item Load \sty{glossaries} \emph{after} \isty{hyperref}: +\begin{verbatim} +\usepackage{hyperref} +\usepackage{glossaries} +\end{verbatim} +Similarly for the \isty{html} package: +\begin{verbatim} +\usepackage{html} +\usepackage{glossaries} +\end{verbatim} + +\item Always use \ics{makeglossaries} if you want the glossary +entries to be written to the glossary file: +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\makeglossaries +\end{verbatim} +If you don't use \ics{makeglossaries}, your glossaries will +not appear in the document! + +\item Use \ics{printglossaries} to make your glossaries appear +in the document at that point. For example: +\begin{verbatim} +\maketitle +\printglossaries +\section{Introduction} +\end{verbatim} +Note that only the glossary entries that have been used in the +document text will appear in the glossary. + +\item When you have created your document, run \LaTeX\ on it, +then the Perl script \appname{makeglossaries}, then run \LaTeX\ +on it again: +\begin{verbatim} +latex myfile +makeglossaries myfile +latex myfile +\end{verbatim} +(You may need to run \LaTeX\ again if you have used the \pkgopt{toc} +package option.) +If you use Windows, there is a batch file called +\texttt{makeglossaries.bat} which you can use, but you will +still need Perl installed. + +\item New glossaries can be defined using:\par +\ics{newglossary}\oarg{log-ext}% +\marg{label}\marg{in-ext}\marg{out-ext}% +\marg{title}\par where \meta{label} is an identifying label, +\meta{in-ext} is the extension of the file to be created +by \appname{makeindex} (called by \appname{makeglossaries}), +\meta{out-ext} is the extension of the file to be read by +\appname{makeindex} and \meta{title} is the title for this +new glossary. The first optional argument \meta{log-ext} specifies +the extension of the \appname{makeindex} transcript file. Example: +\begin{verbatim} +\newglossary[nlg]{notation}{not}{ntn}{Notation} +\end{verbatim} +This glossary's label is \texttt{notation} and its title +will be Notation. If you use \appname{makeglossaries}, the +\appname{makeindex} transcript will be written to a file with the +extension \filetype{.nlg}. If \meta{log-ext} is omitted, the extension +\filetype{.glg} will be used. + +\item Any new glossaries must be defined before +\cs{makeglossaries} +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\newglossary{notation}{not}{ntn}{Notation} +\makeglossaries +\end{verbatim} + +\item If you use the \pkgopt{acronym} package option, the +\sty{glossaries} package +will automatically create a new glossary type labelled +\texttt{acronym}: +\begin{verbatim} +\usepackage[acronym]{glossaries} +\end{verbatim} + +\item If your pages have a hyphen compositor (i.e.\ your page +numbers appear in the form 2-1), redefine \ics{glscompositor} +\emph{before} \ics{makeglossaries}: +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\renewcommand{\glscompositor}{-} +\makeglossaries +\end{verbatim} + +\item To add the glossaries to the table of contents use the +\pkgopt{toc} package option: +\begin{verbatim} +\usepackage[toc]{glossaries} +\end{verbatim} + +\item Define a new entry with:\par +\ics{newglossaryentry}\marg{label}\marg{key-val list}\par +The \meta{key-val list} must at least contain a \gloskey{name} +key and a \gloskey{description} key. +For example: +\begin{verbatim} +\newglossaryentry{perl}{name=Perl, +description=A scripting language} +\end{verbatim} +In this example, I have given the entry the label \texttt{perl}. +Whenever I want to use this entry, that is the label I need +to use to identify it. + +\item If the entry name starts with an accented letter, you will +need to group the first letter (otherwise it will cause a +problem for \ics{Gls} and \ics{Glspl}): +\begin{verbatim} +\newglossaryentry{elite}{name={{\'e}lite}, +description={select group or class}} +\end{verbatim} + +\item If you have multiple glossaries, use the \gloskey{type} +key to specify in which glossary the entry belongs. For example: +\begin{verbatim} +\newglossary{languages}{lan}{lng}{Index of Languages} + +\makeglossaries + +\newglossaryentry{perl}{name=Perl, +description=A scripting language, +type=languages} +\end{verbatim} +If \gloskey{type} is omitted, the default glossary is used. + +\item Remember to group values that have a comma or equal sign. +For example: +\begin{verbatim} +\newglossaryentry{pagelist}{name=page list, +description={A list of individual pages or page ranges +(e.g.\ 1,2,4,7--9)}} +\end{verbatim} + +\item Plural forms are assumed to be the singular form with an +\dq{s} appended, unless otherwise specified. To specify an +irregular plural, use the \gloskey{plural} key. For example: +\begin{verbatim} +\newglossaryentry{matrix}{name=matrix, +description=rectangular array of quantities, +plural=matrices} +\end{verbatim} + +\item The way the term appears in the main text can be different +from the way the term appears in the glossary: +\begin{verbatim} +\newglossaryentry{matrix}{name=Matrix, +description=rectangular array of quantities, +text=matrix, +plural=matrices} +\end{verbatim} +In this example, the entry name appears as \dq{Matrix} in the +glossary, and either \dq{matrix} or \dq{matrices} in the text. + +\item The way the term appears on first use can be different +to the way it appears subsequently: +\begin{verbatim} +\newglossaryentry{singmtx}{name=Singular Matrix, +description=A matrix with a zero determinant, +first=singular matrix (SM), +text=SM, +firstplural=singular matrices (SMs)} +\end{verbatim} +In this example, the entry name appears as \dq{Singular Matrix} in +the glossary, and in the text it appears as \dq{singular matrix (SM)} +or \dq{singular matrices (SMs)} the first time the entry is used, +and subsequently appears as \dq{SM} or \dq{SMs}. + +\item The quick and easy way to define an acronym is to use:\par +\ics{newacronym}\oarg{key-val list}\marg{label}\marg{abbrev}% +\marg{long}\par +For example: +\begin{verbatim} +\newacronym{svm}{SVM}{support vector machine} +\end{verbatim} +This is equivalent to: +\begin{verbatim} +\newglossaryentry{svm}{type=\acronymtype, +name={SVM}, +description={support vector machine}, +text={SVM}, +first={support vector machine (SVM)}, +plural={SVMs}, +firstplural={support vector machines (SVMs)}} +\end{verbatim} +(The value of \ics{acronymtype} varies depending on whether +the \pkgopt{acronym} package option is used or not. +The optional argument \meta{key-val list} can be used to +override any of the \ics{newglossaryentry} keys; for +example, if the acronym has an irregular plural.) + +\item The font used to display the entry name in the glossary +is governed by \ics{glsnamefont}. This can be redefined +as required. For example, to make the entry names appear +in a medium sans-serif font do: +\begin{verbatim} +\renewcommand{\glsnamefont}[1]{\textsf{\mdseries #1}} +\end{verbatim} +Note that the list-like glossary styles defined in the +\isty{glossary-list} package place the entry name in +the optional argument to \ics{item}, so they will +appear in bold, unless you redefine \ics{glsnamefont} to counteract the +bold font. + +\item In the document use \ics{gls}\marg{label} +to use a predefined term (this will also enter the term into +the associated glossary output file). For example: +\begin{verbatim} +A \gls{singmtx} is a matrix with a zero determinant. +\end{verbatim} + +\item Other variations: +\begin{itemize} +\item \ics{Gls}\marg{label} : like \cs{gls}, +but with first letter in upper case +\item \ics{GLS}\marg{label} : like \cs{gls}, +but all upper case. +\item \ics{glspl}\marg{label} : use plural +\item \ics{Glspl}\marg{label} : use plural with +first letter in upper case +\item \ics{GLSpl}\marg{label} : use plural but +all upper case +\item \ics{glslink}\marg{label}\marg{link text} : +use \meta{link text} to link to the given entry in the glossary. +\end{itemize} +For example, the following will produce the plural form with +the first letter in uppercase: +\begin{verbatim} +\Glspl{singmtx} are matrices with a zero determinant. +\end{verbatim} + +\item Additional text can be appended to the link using the +end optional argument. For example, to form the possessive: +\begin{verbatim} +The \gls{singmtx}['s] dimensions \ldots +\end{verbatim} + +\item The format of the associated entry number can be +changed using the \gloskey[glslink]{format} key in the optional argument. +Note that the value of the \gloskey[glslink]{format} key should be the +name of a command \emph{without} the initial backslash. For +example: +\begin{verbatim} +The primary definition of \glspl[format=textbf]{singmtx}. +\end{verbatim} +In this example the relevant glossary entry will have the +page number in bold (since it uses \cs{textbf}) but +it will no longer have a hyperlink (if hyperlinks are enabled.) + +\item The \sty{glossaries} package provides commands to +change the font whilst ensuring that the number remains a +hyperlink. These are of the form \cs{hyper}\meta{xx} and +are equivalent to the standard font changing commands of the +form \cs{text}\meta{xx}, as well as \ics{hyperemph} +(which uses \ics{emph}.) For example: +\begin{verbatim} +The primary definition of \glspl[format=hyperbf]{singmtx}. +\end{verbatim} + +\item Don't use declarations in \gloskey[glslink]{format} as this can +cause unpredictable results, as there is no guarantee that the effect +will be localised to the required text. + +\item Entries can be added to the glossary without producing +any text using \ics{glsadd}\marg{label} or +\ics{glsaddall}. These commands also taken an optional +argument where you can specify the format. For example +\begin{verbatim} +\glsadd[format=hyperbf]{singmtx} +\end{verbatim} +will add a line to the +glossary file for the specified term, but will not produce +any text where the command occurs. + +\item A number range can be entered using \verb|format=(| and +\verb"format=)" to mark the beginning and ending of the +range\footnote{This is new to version 1.01}. For example: +\begin{verbatim} + \glsadd[format=(]{singmtx} + This is a very long section all about \glspl{singmtx}. + + % lots of text omitted + + \glsadd[format=)]{singmtx} +\end{verbatim} +This is equivalent to \appname{makeindex}'s \verb"|(" and \verb"|)" +formats. + +\item You can combine the range markers with a formatting command +(again without the preceding backslash). For example: +\begin{verbatim} + This is the start of a very long section all + about \glspl[format=(hyperbf]{singmtx}. + + % lots of text omitted + + This is the end a very long section all about + \glspl[format=)hyperbf]{singmtx}. +\end{verbatim} + +\item Only those terms that have actually been used in the +document will be placed in the glossary. If you have defined +a term that doesn't appear in the document, then it means +you haven't used it in the text (either via \ics{glslink} +or \ics{gls} and related commands, or via \ics{glsadd} +or \ics{glsaddall}.) + +\item To change the sorting order, use the \gloskey{sort} key. +For example: +\begin{verbatim} +\newglossaryentry{universal}{name={\ensuremath{\mathcal{U}}}, +description=The universal set, +sort=U} +\end{verbatim} + +\item You don't need to escape \appname{makeindex}'s special characters: +\begin{verbatim} +\newglossaryentry{quote}{name={"}, +description={Double quote character}} + +\newglossaryentry{exclam}{name={!}, +description={Exclamation mark}} + +\newacronym{rna}{RNA}{ribonukleins\"aure} +\end{verbatim} + +\item Associated symbols can also be specified, but whether the +symbol appears in the glossary depends on the glossary style. +For example: +\begin{verbatim} +\newglossaryentry{metre}{name={metre}, +description={A metric measurement of length}, +symbol={m}} +\end{verbatim} +The predefined glossary styles that display the entry symbol +are: \glostyle{long4col}, \glostyle{long4colheader}, +\glostyle{long4colborder}, \glostyle{long4colheaderborder}, +\glostyle{super4col}, \glostyle{super4colheader}, +\glostyle{super4colborder} and \glostyle{super4colheaderborder}. +All the other styles supplied by this package ignore the associated +symbol. + +\item Glossary styles can be set using the \pkgopt{style} +package option. For example: +\begin{verbatim} +\usepackage[style=long3col]{glossaries} +\end{verbatim} +or using \ics{glossarystyle}\marg{style}. For example: +\begin{verbatim} +\glossarystyle{altlist} +\end{verbatim} +The predefined glossary styles provided by the \sty{glossaries} +bundle are listed in \ifmakedtx{\autoref{sec:styles}}{\htmlref{{Glossary Styles}}{sec:styles}}. + +\item The list of numbers associated with each glossary entry +can be suppressed using the package option \pkgopt{nonumberlist}: +\begin{verbatim} +\usepackage[nonumberlist]{glossaries} +\end{verbatim} + +\item By default, the glossaries will appear in an unnumbered +chapter if chapters are defined, otherwise in an unnumbered +section. This can be changed using the \pkgopt{section} package +option. For example, to make the glossaries appear in an unnumbered +section, even if chapters are defined, do: +\begin{verbatim} +\usepackage[section]{glossaries} +\end{verbatim} +Other sectional units can also be specified as +\pkgopt{section}=\meta{value}. For example, to make the glossaries +appear in unnumbered subsections: +\begin{verbatim} +\usepackage[section=subsection]{glossaries} +\end{verbatim} + +\end{enumerate}\ifmakedtx{}{\toTop} + +\section{Overview}\label{sec:overview} + \changes{1.02}{2007 May 25}{added overview section} + +\subsection{Package Options} + +The \sty{glossaries} package options are as follows: +\begin{description} +\item[\pkgopt{toc}] Add the glossaries to the table of contents. + +\item[\pkgopt{numberline}] When used with \pkgopt{toc}, this will +add \cs{numberline}\verb|{}| in the final argument of +\cs{addcontentsline}. This will align the table of contents entry +with the numbered section titles. Note that this option has no +effect if the \pkgopt{toc} option is omitted. If \pkgopt{toc} is +used without \pkgopt{numberline}, the title will be aligned with +the section numbers rather than the section titles. + +\item[\pkgopt{acronym}] Make a separate glossary for acronyms. + +\item[\pkgopt{section}] This is a \meta{key}=\meta{value} option. Its +value should be the name of a sectional unit (e.g.\ chapter). +This will make the glossaries appear in the named sectional unit, +otherwise each glossary will appear in a chapter, if chapters +exists, otherwise in a section. Unnumbered sectional units will be used +by default. Example: +\begin{verbatim} +\usepackage[section=subsection]{glossaries} +\end{verbatim} +You can omit the value if you want to use sections, i.e.\ +\begin{verbatim} +\usepackage[section]{glossaries} +\end{verbatim} +is equivalent to +\begin{verbatim} +\usepackage[section=section]{glossaries} +\end{verbatim} +You can change this value later in the document using +\ics{setglossarysection}\marg{type}. + +\item[\pkgopt{numberedsection}] +The glossaries are placed in unnumbered sectional units by default, +but this can be changed using \pkgopt{numberedsection}. This option can take +three possible values: \pkgoptval{false}{numberedsection} (no +number, i.e.\ use starred form), \pkgoptval{nolabel}{numberedsection} +(numbered, i.e.\ unstarred form, but not labelled) and +\pkgoptval{autolabel}{numberedsection} (numbered with automatic +labelling). If \pkgopt[autolabel]{numberedsection} is used, each +glossary is given a label that matches the glossary type, so the +main (default) glossary is labelled \texttt{main}, the list of +acronyms is labelled \texttt{acronym}\footnote{if the +\pkgopt{acronym} option is used, otherwise the list of +acronyms is the main glossary} and additional glossaries are labelled +using the value specified in the first mandatory argument to +\cs{newglossary}. For example, if you load \sty{glossaries} +using: +\begin{verbatim} +\usepackage[section,numberedsection=autolabel]{glossaries} +\end{verbatim} +then each glossary will appear in a numbered section, and can +be referenced using something like: +\begin{verbatim} +The main glossary is in section~\ref{main} and the list of +acronyms is in section~\ref{acronym}. +\end{verbatim} +If you can't decide whether to have the acronyms in the main +glossary or a separate list of acronyms, you can use +\ics{acronymtype} which is set to \texttt{main} if the +\pkgopt{acronym} option is not used and is set to \texttt{acronym} +if the \pkgopt{acronym} option is used. For example: +\begin{verbatim} +The list of acronyms is in section~\ref{\acronymtype}. +\end{verbatim} + +\item[\pkgopt{style}] This is a \meta{key}=\meta{value} option. Its +value should be the name of the glossary style to use. Predefined +glossary styles are listed \ifmakedtx{in \autoref{sec:styles}}{\htmlref{later}{sec:styles}}. + +\item[\pkgopt{nonumberlist}] This option will suppress the +associated number lists\iterm{number list} in the glossaries (see also +\ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}.) + +\item[\pkgopt{counter}] This is a \meta{key}=\meta{value} option. The +value should be the name of the default counter to use in the number +lists\iterm{number list}. + +\ifmakedtx{\hypertarget{sanitize}{}\relax}{\label{sanitize}} +\item[\pkgopt{sanitize}] This is a \meta{key}=\meta{value} option whose +value is also a \meta{key}=\meta{value} list. By default, the +\sty{glossaries} package sanitizes the values of the +\gloskey{name}, \gloskey{description} and \gloskey{symbol} keys used +when defining a new glossary entry. This 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. \ifmakedtx{(See \autoref{sec:pkgopt} and \autoref{sec:newentry} for +further details.)}{} 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} + +\textbf{Note}: this sanitization only applies to the \gloskey{name}, +\gloskey{description} and \gloskey{symbol} keys. It doesn't apply +to any of the other keys (except the \gloskey{sort} key which is +always sanitized) 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. + +\item[\pkgopt{babel}] This is a boolean key and is for use when +the \sty{glossaries} package is used in conjunction with the +\isty{babel} package. The default is \pkgopt[true]{babel}, which +adds the glossary translations to \isty{babel}'s captions. If +you don't like the translations provided by the \sty{glossaries} +package, you can set \pkgopt[false]{babel} and provide your own +translations. + +\item[\pkgopt{description}] This option changes the definition of +\ics{newacronym} to allow a description. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} +for further details. + +\item[\pkgopt{footnote}] This option changes the definition of +\ics{newacronym} and the way that acronyms are displayed. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} +for further details. + +\item[\pkgopt{smallcaps}] This option changes the definition of +\ics{newacronym} and the way that acronyms are displayed. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} +for further details. + +\item[\pkgopt{dua}] This option changes the definition of +\ics{newacronym} so that acronyms are always expanded. +See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} +for further details. + +\end{description}\ifmakedtx{}{\toTop} + +\subsection{Defining Glossary Entries} +\label{sec:newglosentry} + +All glossary entries that are used in a document must be defined in +the preamble. Only those entries that occur in the document +(using any of the commands described in \ifmakedtx{\autoref{sec:glslink}}{\htmlref{Links to Glossary Entries}{sec:glslink}} and +\ifmakedtx{\autoref{sec:glsadd}}{\htmlref{Adding an entry to the glossary without generating text}{sec:glsadd}}) will appear in the glossary. Each time an entry +is used in this way, a line is added to an associated glossary +(\filetype{.glo}) file, which then needs to be converted into a +corresponding \filetype{.gls} file which contains the typeset glossary +which is input by \ics{printglossary} or +\ics{printglossaries}. The Perl script \appname{makeglossaries} +can be used to call \appname{makeindex}, using a customised +\filetype{.ist} style file, for each of the glossaries that are defined +in the document. Note that there should be no need for you to +explicitly edit or input any of these external files. + +\DescribeMacro{\makeglossaries} +The command \cs{makeglossaries} must be placed in the preamble in +order to create the customised \appname{makeindex} \filetype{.ist} +style file and to ensure that glossary entries are written to the +appropriate output file. If you omit \cs{makeglossaries} none of the +glossaries will be created. Note that if your page numbers use a +hyphen compositor, you must set this by redefining +\DescribeMacro{\glscompositor}\cs{glscompositor} \emph{before} +using \cs{makeglossaries}: +\begin{verbatim} +\renewcommand*{\glscompositor}{-} +\end{verbatim} +(The default value of \cs{glscompositor} is a full stop.) + +\DescribeMacro{\newglossaryentry} +New glossary entries are defined using the command:\\[10pt] +\cs{newglossaryentry}\marg{label}\marg{key-val list}\\[10pt] The first +argument, \meta{label}, must be a unique label with which to identify +this entry. The second argument, \meta{key-val list}, is a +\meta{key}=\meta{value} list that supplies the relevant information +about this entry. There are two required fields: \gloskey{name} and +\gloskey{description}. Available fields are listed below: + +\begin{description} +\item[{\gloskey{name}}] The name of the entry (as it will appear in the +glossary). + +\item[{\gloskey{description}}] A brief description of this term (to +appear in the glossary). + +\item[{\gloskey{text}}] How this entry will appear in the document text +when using \ics{gls} (or one of its uppercase variants). If this +field is omitted, the value of the \gloskey{name} key is used. + +\item[{\gloskey{first}}] How the entry will appear in the document text +the first time it is used with \ics{gls} (or one of its uppercase +variants). If this field is omitted, the value of the \gloskey{text} +key is used. + +\item[{\gloskey{plural}}] How the entry will appear in the document text +when using \ics{glspl} (or one of its uppercase variants). +If this field is omitted, the value is obtained by appending an +\dq{s} to the value of the \gloskey{text} field. + +\item[{\gloskey{firstplural}}] How the entry will appear in the document +text the first time it is used with \ics{glspl} (or one of +its uppercase variants). If this field is omitted, the value is +obtained by appending an \dq{s} to the value of the \gloskey{first} +field. + +\item[{\gloskey{symbol}}] This field is provided to allow the user to +specify an associated symbol, but most glossary styles ignore +this value. If omitted, the value is set to \cs{relax}. + +\item[{\gloskey{sort}}] This value indicates how \appname{makeindex} +should sort this entry. If omitted, the value is given by the +\gloskey{name} field. This value is equivalent to +\appname{makeindex}'s \dq{actual} character (which is usually the +at-sign @ although the \sty{glossaries} package uses a different +symbol). + +\item[{\gloskey{type}}] This is the glossary type to which this entry +belongs. If omitted, the default glossary is assumed +(\texttt{type=main}). The list of acronyms type is given by +\ics{acronymtype} which will either be \texttt{main} or +\texttt{acronym}, depending on whether the \pkgopt{acronym} package +option was used. +\end{description} +Note that if the \gloskey{text} key (or the \gloskey{name} key, if the +\gloskey{text} key is omitted) starts with an accented letter, +you must group the accented letter, otherwise it will cause a +problem for \cs{Gls} and \cs{Glspl}. For example: +\begin{verbatim} +\newglossaryentry{elite}{name={{\'e}lite}, +description={select group or class}} +\end{verbatim} +(Likewise for the \gloskey{plural}, \gloskey{first} and +\gloskey{firstplural} keys.) + +\DescribeMacro{\loadglsentries} +You can store all your glossary entry definitions in another +file, and use:\\[10pt] +\cs{loadglsentries}\oarg{type}\marg{filename}\\[10pt] +where \meta{filename} is the name of the file containing all the +\cs{newglossaryentry} commands. The optional argument +\meta{type} is the name of the glossary to which those entries +should belong, for those entries where the \gloskey{type} key has +been omitted. Note that only those entries that have been used +in the text will appear in the relevant glossaries.\ifmakedtx{}{\toTop} + +\subsection{Number lists} +\label{sec:numberlists} + +Each entry in the glossary has an associated \termdef{number list}. +By default, +these numbers refer to the pages on which that entry has been used +(using any of the commands described in \ifmakedtx{\autoref{sec:glslink}}{\htmlref{Links to Glossary Entries}{sec:glslink}} +and \ifmakedtx{\autoref{sec:glsadd}}{\htmlref{Adding an entry to the glossary without generating text}{sec:glsadd}}). The number 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.\ifmakedtx{}{\toTop} + +\subsection{Links to Glossary Entries} +\label{sec:glslink} + +Once you have defined a glossary entry using +\ics{newglossaryentry}, you can refer to that entry in the +document using one of the commands listed in this section. The +text which appears at that point in the document when using +one of these commands is referred to as the +\termdef{link text} (even if there are no hyperlinks). + +The way the \term{link text} is displayed +depends on \DescribeMacro{\glstextformat}\cs{glstextformat}\marg{text}. +For example, to make all \term{link text} appear in a sans-serif +font, do: +\begin{verbatim} +\renewcommand*{\glstextformat}[1]{\textsf{#1}} +\end{verbatim} + +\DescribeMacro{\glslink} +The command:\\[10pt] +\cs{glslink}\oarg{options}\marg{label}\marg{text}\\[10pt] +will place \meta{text} in the document at that point and add +a line into the associated glossary file for the glossary entry +given by \meta{label}. If hyperlinks are supported, \meta{text} +will be a hyperlink to the relevant line in the glossary. The +optional argument \meta{options} must be a \meta{key}=\meta{value} +list which can take any of the following keys: + +\begin{description} +\item[{\gloskey[glslink]{format}}] This specifies how to format the +associated number for this entry in the glossary. This value is +equivalent to the \appname{makeindex} encap value, and (as with +\cs{index}) the value needs to be the name of a command \emph{without} +the initial backslash. As with \cs{index}, the characters \verb"(" and +\verb")" can also be used to specify the beginning and ending of a +number range. Again as with \cs{index}, the command should be the name +of a command which takes an argument (which will be the associated +number). Be careful not to use a declaration (such as \cs{bfseries}) +instead of a text block command (such as \cs{textbf}) as the effect is +not guaranteed to be localised. If you want to apply more than one +style to a given entry (e.g.\ \textbf{bold} and \emph{italic}) you will +need to create a command that applies both formats, e.g.\ +\begin{verbatim} +\newcommand*{\textbfem}[1]{\textbf{\emph{#1}}} +\end{verbatim} +and use that command. + +If you are using hyperlinks and you want to change the font of the +hyperlink, don't use \cs{hyperpage} (provided by the \isty{hyperref} +package) as the numbers may not refer to a page number. +Instead, the \sty{glossaries} package provides the following +number formats: +\begin{center} +\ifmakedtx{\begin{tabular}{@{\sffamily}lp{0.8\linewidth}} +hyperrm & The number is a serif hyperlink to the relevant part of the +document\\ +hypersf & The number is a sans-serif hyperlink to the relevant part +of the document\\ +hypertt & The number is a monospaced hyperlink to the relevant part +of the document\\ +hyperbf & The number is a bold hyperlink to the relevant part of the +document\\ +hypermd & The number is a medium weight hyperlink to the relevant +part of the document\\ +hyperit & The number is an italic hyperlink to the relevant +part of the document\\ +hypersl & The number is a slanted hyperlink to the relevant +part of the document\\ +hyperup & The number is an upright hyperlink to the relevant +part of the document\\ +hypersc & The number is a small caps hyperlink to the relevant +part of the document\\ +hyperemph & The number is an emphasized hyperlink to the relevant +part of the document +\end{tabular}}{\begin{tabular}{ll} +\texttt{hyperrm} & The number is a serif hyperlink to the relevant part of the +document\\ +\texttt{hypersf} & The number is a sans-serif hyperlink to the relevant part +of the document\\ +\texttt{hypertt} & The number is a monospaced hyperlink to the relevant part +of the document\\ +\texttt{hyperbf} & The number is a bold hyperlink to the relevant part of the +document\\ +\texttt{hypermd} & The number is a medium weight hyperlink to the relevant +part of the document\\ +\texttt{hyperit} & The number is an italic hyperlink to the relevant +part of the document\\ +\texttt{hypersl} & The number is a slanted hyperlink to the relevant +part of the document\\ +\texttt{hyperup} & The number is an upright hyperlink to the relevant +part of the document\\ +\texttt{hypersc} & The number is a small caps hyperlink to the relevant +part of the document\\ +\texttt{hyperemph} & The number is an emphasized hyperlink to the relevant +part of the document +\end{tabular}} +\end{center} +Note that if the \cs{hyperlink} command hasn't been defined, +the \texttt{hyper}\meta{xx} formats are equivalent to the +analogous \cs{text}\meta{xx} font commands. If you want to +make a new format, you will need to define a command which takes +one argument and use that; for example, if you want the associated +number in the glossary to be in a bold sans-serif font, you can define a +command called, say, \cs{hyperbsf}: +\begin{verbatim} +\newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}} +\end{verbatim} +and then use \texttt{hyperbsf} as the value for the \gloskey{format} +key.\ifmakedtx{ (See also \autoref{sec:printglos}.)}{} + +\item[{\gloskey[glslink]{counter}}] This specifies which counter +to use for the associated number for this glossary entry. (See also +\ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}.) + +\item[{\gloskey[glslink]{hyper}}] This is a boolean key which can +be used to enable/disable the hyperlink to the relevant entry +in the glossary. (Note that setting \texttt{hyper=true} will have no +effect if \cs{hyperlink} has not been defined.) The default +value is \texttt{hyper=true}. + +\end{description} +\DescribeMacro{\glslink*} +There is also a starred version:\\[10pt] +\cs{glslink*}\oarg{options}\marg{label}\marg{text}\\[10pt] +which is equivalent to \cs{glslink}, except it sets +\texttt{hyper=false}. + +\DescribeMacro{\gls} +The command:\\[10pt] +\cs{gls}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +is the same as \cs{glslink}, except that the \term{link text} +is determined from the values of the \gloskey{text} and +\gloskey{first} keys supplied when the entry was defined using +\ics{newglossaryentry}. There are two uppercase variants:\\[10pt] +\DescribeMacro{\Gls} +\cs{Gls}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +and\\[10pt] +\DescribeMacro{\GLS} +\cs{GLS}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +which make the first letter of the link or all the link text +uppercase, respectively. + +The final optional argument \meta{insert}, allows you to insert +some additional text into the link text. By default, this will +append \meta{insert} at the end of the link text. The first optional +argument \meta{options} is the same as the optional argument to +\ics{glslink}. As with \cs{glslink}, these commands also have +a starred version that disable the hyperlink. + +There are also analogous plural forms:\\[10pt] +\DescribeMacro{\glspl} +\cs{glspl}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +\DescribeMacro{\Glspl} +\cs{Glspl}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +\DescribeMacro{\GLSpl} +\cs{GLSpl}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +These determine the link text from the \gloskey{plural} and +\gloskey{firstplural} keys supplied when the entry was first +defined. As before, these commands also have +a starred version that disable the hyperlink. + +\DescribeMacro{\glstext}The command:\\[10pt] +\cs{glstext}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +is similar to \ics{gls} except that it always uses the value +of the \gloskey{text} key and does not mark the entry as +having been used. + +There are also analogous commands:\\[10pt] +\DescribeMacro{\Glstext} +\cs{Glstext}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +\DescribeMacro{\GLStext} +\cs{GLStext}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +As before, these commands also have a starred version that disable +the hyperlink. + +\DescribeMacro{\glsfirst}The command:\\[10pt] +\cs{glsfirst}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +is similar to \ics{gls} except that it always uses the value +of the \gloskey{first} key and does not mark the entry as +having been used. + +There are also analogous commands:\\[10pt] +\DescribeMacro{\Glsfirst} +\cs{Glsfirst}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +\DescribeMacro{\GLSfirst} +\cs{GLSfirst}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +As before, these commands also have a starred version that disable +the hyperlink. + +\DescribeMacro{\glsplural}The command:\\[10pt] +\cs{glsplural}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +is similar to \ics{gls} except that it always uses the value +of the \gloskey{plural} key and does not mark the entry as +having been used. + +There are also analogous commands:\\[10pt] +\DescribeMacro{\Glsplural} +\cs{Glsplural}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +\DescribeMacro{\GLSplural} +\cs{GLSplural}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +As before, these commands also have a starred version that disable +the hyperlink. + +\DescribeMacro{\glsfirstplural}The command:\\[10pt] +\cs{glsfirstplural}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +is similar to \ics{gls} except that it always uses the value +of the \gloskey{firstplural} key and does not mark the entry as +having been used. + +There are also analogous commands:\\[10pt] +\DescribeMacro{\Glsfirstplural} +\cs{Glsfirstplural}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +\DescribeMacro{\GLSfirstplural} +\cs{GLSfirstplural}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +As before, these commands also have a starred version that disable +the hyperlink. + +\DescribeMacro{\glsname}The command:\\[10pt] +\cs{glsname}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +is similar to \ics{gls} except that it always uses the value +of the \gloskey{name} key and does not mark the entry as +having been used. Note: if you want to use this command and the +\gloskey{name} key contains commands, you will have to disable the +\ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} +of the \gloskey{name} key and protect fragile commands. + +There are also analogous commands:\\[10pt] +\DescribeMacro{\Glsname} +\cs{Glsname}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +\DescribeMacro{\GLSname} +\cs{GLSname}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +As before, these commands also have a starred version that disable +the hyperlink. + +\DescribeMacro{\glssymbol}The command:\\[10pt] +\cs{glssymbol}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +is similar to \ics{gls} except that it always uses the value +of the \gloskey{symbol} key and does not mark the entry as +having been used. Note: if you want to use this command and the +\gloskey{symbol} key contains commands, you will have to disable the +\ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} +of the \gloskey{symbol} key and protect fragile commands. + +There are also analogous commands:\\[10pt] +\DescribeMacro{\Glssymbol} +\cs{Glssymbol}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +\DescribeMacro{\GLSsymbol} +\cs{GLSsymbol}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +As before, these commands also have a starred version that disable +the hyperlink. + +\DescribeMacro{\glsdesc}The command:\\[10pt] +\cs{glsdesc}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +is similar to \ics{gls} except that it always uses the value +of the \gloskey{description} key and does not mark the entry as +having been used. Note: if you want to use this command and the +\gloskey{description} key contains commands, you will have to disable the +\ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} +of the \gloskey{description} key and protect fragile commands. + +There are also analogous commands:\\[10pt] +\DescribeMacro{\Glsdesc} +\cs{Glsdesc}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +\DescribeMacro{\GLSdesc} +\cs{GLSdesc}\oarg{options}\marg{text}\oarg{insert}\\[10pt] +As before, these commands also have a starred version that disable +the hyperlink. + +\ifmakedtx{}{\toTop} + +\subsubsection{Changing the format of the link text} +\label{sec:glsdisplay} + +The format of the \term{link text} for \ics{gls}, \ics{glspl} +and their uppercase variants is governed by two commands: +\DescribeMacro{\glsdisplayfirst}\cs{glsdisplayfirst}, which is used the +first time a glossary entry is used in the text and +\DescribeMacro{\glsdisplay}\cs{glsdisplay}, which is used subsequently. +Both commands take four arguments: the first is either the singular or +plural form given by the \gloskey{text}, \gloskey{plural}, +\gloskey{first} or \gloskey{firstplural} keys (used when the term was +defined) depending on context; the second argument is the term's +description (as supplied by the \gloskey{description} key); the third +argument is the symbol associated with the term (as supplied by the +\gloskey{symbol} key) and the fourth argument is the additional text +supplied in the final optional argument to \cs{gls} or +\cs{glspl} (or their uppercase variants). The default definitions +of \cs{glsdisplay} and \cs{glsdisplayfirst} simply +print the first argument immediately followed by the fourth argument. +The remaining arguments are ignored. + +For example, 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, +description={The length between two points}, +symbol={km}} +\end{verbatim} +and now suppose you want \verb|\gls{distance}| to produce +\dq{distance (km)} on first use, then you can redefine +\cs{glsdisplayfirst} as follows: +\begin{verbatim} +\renewcommand{\glsdisplayfirst}[4]{#1#4 (#3)} +\end{verbatim} +Note that the additional text is placed after \verb|#1|, so +\verb|\gls{distance}['s]| will produce \dq{distance's (km)} +rather than \dq{distance (km)'s} which looks a bit odd (even though +it may be in the context of \dq{the distance (km) is measured between +the two points} --- but in this instance it may be better not to +use a contraction). + +Note also that all of the \term{link text} 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)} +\end{verbatim} +then \verb|\gls{distance}| will produce \dq{\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 commands \cs{gls}, \cs{glspl} and their +uppercase variants. If you only +want the change to affect entries for a given glossary, then you need +to use \DescribeMacro{\defglsdisplay}\cs{defglsdisplay} and +\DescribeMacro{\defglsdisplayfirst}\cs{defglsdisplayfirst} instead +of redefining \cs{glsdisplay} and \cs{glsdisplayfirst}. + +Both \cs{defglsdisplay} and \cs{defglsdisplayfirst} take two arguments: +the first (which is optional) is the glossary name\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} and their uppercase variants. This is similar to the way \cs{glsdisplayfirst} was +redefined above. + +For example, suppose you have created a new glossary called +\texttt{notation} and you want to change the way the entry is +displayed on first use so that it includes the symbol, you can +do: +\begin{verbatim} +\defglsdisplayfirst[notation]{#1#4 (denoted #3)} +\end{verbatim} +Now suppose you have defined an entry as follows: +\begin{verbatim} +\newglossaryentry{set}{type=notation, +name=set, +description={A collection of objects}, +symbol={$S$}, +} +\end{verbatim} +The first time you reference this entry using \cs{gls} it +will be displayed as: \dq{set (denoted \ifmakedtx{$S$}{\textit{S}})} +(similarly for \cs{glspl} and the uppercase variants). + +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 \term{link text}, you will have to disable the +\ifmakedtx{\hyperlink{sanitize}{sanitization}}{\htmlref{sanitization}{sanitize}} +of these keys and protect fragile commands.\ifmakedtx{}{\toTop} + +\subsubsection{Enabling and disabling hyperlinks to glossary entries} + +If you load the \isty{hyperref} or \isty{html} packages prior to +loading the \sty{glossaries} package, commands such as \ics{glslink} +and \ics{gls}, described above, will automatically have hyperlinks +to the relevant glossary entry, unless the \gloskey[glslink]{hyper} +option has been set to \texttt{false}. You can disable or enable links using:\\[10pt] +\DescribeMacro{\glsdisablehyper}\cs{glsdisablehyper}\\[10pt] +and\\[10pt] +\DescribeMacro{\glsenablehyper}\cs{glsenablehyper}\\[10pt] +respectively. The effect can be localised by placing the commands +within a group. Note that you should only use \cs{glsenablehyper} +if the commands \ics{hyperlink} and \ics{hypertarget} have been +defined (for example, by the \isty{hyperref} package). + +\subsection{Adding an entry to the glossary without generating text} +\label{sec:glsadd} + +\DescribeMacro{\glsadd} +It is possible to add a line in the glossary file without +generating any text at that point in the document using:\\[10pt] +\cs{glsadd}\oarg{options}\marg{label}\\[10pt] +This is similar to \ics{glslink}, only it doesn't produce +any text (so therefore, there is no \gloskey[glslink]{hyper} key +available in \meta{options} but all the other options that can +be used with \cs{glslink} can be passed to \cs{glsadd}). + +\DescribeMacro{\glsaddall} +To add all entries that have been defined, use:\\[10pt] +\cs{glsaddall}\oarg{glossary list}\\[10pt] +If there are multiple glossaries, you can specify to add only +those entries which belong to the glossaries listed in +\meta{glossary list} (which must be a comma separated list of +glossary names). For example: +\begin{verbatim} +\glsaddall[notation] +\end{verbatim} +will add all the entries that have been defined for the glossary +labelled \dq{notation}.\ifmakedtx{}{\toTop} + +\subsection{Displaying a glossary} + +\DescribeMacro{\printglossaries} +The command \cs{printglossaries} will display all the +defined glossaries. Note that no glossaries will appear until +you have either used the Perl script \appname{makeglossaries} +or have directly used \appname{makeindex} (as described in +\ifmakedtx{\autoref{sec:makeglossaries}}{\htmlref{Generating the Associated Glossary Files}{sec:makeglossaries}}). If the glossary still +does not appear after you re-\LaTeX\ your document, check +the \appname{makeindex} 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. + +\DescribeMacro{\printglossary} +An individual glossary is displayed using:\\[10pt] +\cs{printglossary}\oarg{options}\\[10pt] +where \meta{options} is a \meta{key}=\meta{value} list of options. +The following keys are available: +\begin{description} +\item[{\gloskey[printglossary]{type}}] The value of this key +specifies which glossary to print. If omitted, the default +glossary is assumed. For example, to print the list of acronyms: +\begin{verbatim} +\printglossary[type=\acronymtype] +\end{verbatim} + +\item[{\gloskey[printglossary]{title}}] This is the glossary's +title (overriding the title specified when the glossary was +defined). + +\item[{\gloskey[printglossary]{toctitle}}] This is the title +to use for the table of contents (if the \pkgopt{toc} package +option has been used). If omitted, the glossary title is used. + +\item[{\gloskey[printglossary]{style}}] This specifies which +glossary style to use for this glossary, overriding the effect +of the \pkgopt{style} option or \ics{glossarystyle}. +\end{description} + +\DescribeMacro{\glossarypreamble} +Information can be added to the start of the glossary by redefining +\cs{glossarypreamble}. For example: +\begin{verbatim} +\renewcommand{\glossarypreamble}{Numbers in italic indicate +primary definitions.} +\end{verbatim} +This needs to be done before the glossary is displayed using +\cs{printglossaries} or \cs{printglossary}. Note that if you +want a different preamble for each glossary, you will need to +use a separate \cs{printglossary} for each glossary and change +the definition of \cs{glossarypreamble} between each glossary. +For example: +\begin{verbatim} +\renewcommand{\glossarypreamble}{Numbers in italic indicate +primary definitions.} +\printglossary +\renewcommand{\glossarypreamble}{} +\printglossary[type=acronym] +\end{verbatim} +Alternatively, you can do something like: +\begin{verbatim} +\renewcommand{\glossarypreamble}{Numbers in italic indicate +primary definitions.\gdef\glossarypreamble{}} +\printglossaries +\end{verbatim} +which will print the preamble text for the first glossary and +change the preamble to do nothing for subsequent glossaries. +(Note that \cs{gdef} is required as the glossary is placed within +a group.) + +\DescribeMacro{\glossarypostamble}There is an analogous command +called \cs{glossarypostamble} which is placed at the end of each +glossary.\ifmakedtx{}{\toTop} + +\subsubsection{Changing the way the entry name appears in the glossary} +\label{sec:glsnamefont} + +\DescribeMacro{\glsnamefont}Within each glossary, each entry name is +formatted according to \cs{glsnamefont} which takes one argument: the +entry name. This command is always used regardless of the glossary +style. By default, \cs{glsnamefont} simply displays its argument in +whatever the surrounding font happens to be. This means that in the +list styles the name will appear in bold, since the name is placed in +the optional argument of \cs{item}, whereas in the tabular styles the +name will appear in the normal font. + +For example, suppose you want all the entry names to appear in +medium weight small caps, then you can do: +\begin{verbatim} +\renewcommand{\glsnamefont}[1]{\textsc{\mdseries #1}} +\end{verbatim} +\ifmakedtx{}{\toTop} + +\subsection{Defining New Glossaries} + +\DescribeMacro{\newglossary} +A new glossary can be defined using:\\[10pt] +\cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\marg{title}\oarg{counter}\\[10pt] +where \meta{name} is label to assign to this glossary. The arguments +\meta{in-ext} and \meta{out-ext} specify the extensions to give to the +input and output files for that glossary, \meta{title} is the default +title for this new glossary and the final optional argument +\meta{counter} specifies which counter to use for the associated number +lists\iterm{number list} (see also \ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}.) The +first optional argument specifies the extension for the +\appname{makeindex} transcript file (this information is only used by +\appname{makeglossaries} which picks up the information from the +auxiliary file.) + +Note that the main (default) glossary is automatically created as: +\begin{verbatim} +\newglossary{main}{gls}{glo}{\glossaryname} +\end{verbatim} +so it can be identified by the label \texttt{main}. Using the +\pkgopt{acronym} package option is equivalent to: +\begin{verbatim} +\newglossary[alg]{acronym}{acr}{acn}{\acronymname} +\end{verbatim} +so it can be identified by the label \texttt{acronym}. If you are +not sure whether the \pkgopt{acronym} option has been used, you +can identify the list of acronyms by the command +\DescribeMacro{\acronymtype}\cs{acronymtype} which is set to +\texttt{acronym}, if the \pkgopt{acronym} option has been used, +otherwise it is set to \texttt{main}.\ifmakedtx{}{\toTop} + +\subsection{Acronyms} +\label{sec:acronyms} + +\DescribeMacro{\newacronym} +As you may have noticed in \ifmakedtx{\autoref{sec:newglosentry}}{\htmlref{Defining Glossary Entries}{sec:newglosentry}}, when you +specify a new entry, you can specify alternate text to use when +the term is first used in the document. This provides a useful +means to define acronyms. The \sty{glossaries} package defines +the command:\\[10pt] +\cs{newacronym}\oarg{key-val list}\marg{label}\marg{abbrv}\marg{long}\\[10pt] +This is equivalent to:\vskip5pt +\begin{ttfamily}\par\noindent +\cs{newglossaryentry}\textrm{\marg{label}}\{type=\cs{acronymtype},\\ +name=\textrm{\marg{abbrv}},\\ +description=\textrm{\marg{long}},\\ +text=\textrm{\marg{abbrv}},\\ +first=\{\textrm{\meta{long}} (\textrm{\meta{abbrv}})\},\\ +plural=\{\textrm{\meta{abbrv}}s\},\\ +firstplural=\{\textrm{\meta{long}}s (\textrm{\meta{abbrv}}s)\},\\ +\textrm{\meta{key-val list}}\}\par +\end{ttfamily} +\vskip5pt +As mentioned in the previous section, the command \cs{acronymtype} is +the name of the glossary in which the acronyms should appear. If the +\pkgopt{acronym} package option has been used, this will be +\texttt{acronym}, otherwise it will be \texttt{main}. The acronyms can +then be used in exactly the same way as any other glossary entry. +For example, the following defines the acronym IDN: +\begin{verbatim} +\newacronym{idn}{IDN}{identification number} +\end{verbatim} +This is equivalent to: +\begin{verbatim} +\newglossaryentry{idn}{type=\acronymtype, +name={IDN}, +description={identification number}, +text={IDN}, +first={identification number (IDN)}, +plural={IDNs}, +firstplural={identification numbers (IDNs)}} +\end{verbatim} +so \verb|\gls{idn}| will produce \dq{identification number (IDN)} on +first use and \dq{IDN} on subsequent uses. + +The \sty{glossaries} package has options that change the +definition of \ics{newacronym} for common acronym formats. These +options also change the way the link text is displayed for the +acronyms. + +Table~\ref{tab:acronymsettings} lists the package options and +how the keys are used to store \meta{long} (the long form) and +\meta{abbrv} (the short form). Note that the \pkgopt{smallcaps} +option redefines \ics{acronymfont} so that it sets its argument +in small captials otherwise \cs{acronymfont} simply displays its +argument in the surrounding font. Note also that if none of +the package options \pkgopt{smallcaps}, \pkgopt{description} +or \pkgopt{footnote} are used, \cs{acronymfont} is not used, so +changing the definition of \cs{acronymfont} will have no effect +under such circumstances. + +\begin{table}[htbp] +\caption{Package options governing acronyms and how the information +is stored in the glossary keys} +\label{tab:acronymsettings} +\begin{center} +\begin{tabular}{lllll} +\bfseries Package Option & +\gloskey{first} & +\gloskey{text} & +\gloskey{description} & +\gloskey{symbol}\\ +\pkgopt{description},\pkgopt{footnote} & +\meta{abbrv} & +\meta{abbrv} & +user supplied & +\meta{long}\\ +\pkgopt{description},\pkgopt{dua} & +\meta{long} & +\meta{long} & +user supplied & +\meta{abbrv}\\ +\pkgopt{description} & +\meta{long} & +\meta{abbrv} & +user supplied & +\meta{abbrv}\\ +\pkgopt{footnote} & +\meta{abbrv} & +\meta{abbrv} & +\meta{long} & + \\ +\pkgopt{smallcaps} & +\meta{long} & +\meta{abbrv} & +\meta{long} & +\meta{abbrv}\\ +\pkgopt{dua} & +\meta{long} & +\meta{long} & +\meta{long} & +\meta{abbrv}\\ +None of the above& +\meta{long} (\meta{abbrv}) & +\meta{abbrv} & +\meta{long} & +\end{tabular} +\end{center} +\end{table} + +Each of the package options \pkgopt{smallcaps}, \pkgopt{footnote} +and \pkgopt{description} use \ics{defglsdisplay} and +\ics{defglsdisplayfirst} (described \ifmakedtx{in +\autoref{sec:glsdisplay}}{\htmlref{earlier}{sec:glsdisplay}}) +to change the way the link text is displayed. + +\begin{description} +\item[\pkgopt{description},\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{} +When these two options are used together, the first use displays +the entry as:\\[10pt] +\cs{acronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long} +\\[10pt] +while subsequent use displays the entry as:\\[10pt] +\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt] +where \meta{insert} indicates the text supplied in the final +optional argument to \cs{gls}, \cs{glspl} or their uppercase +variants. + +Note also that when these two package options are used (in the +given order), the \sty{glossaries} package additionally implements the +\pkgopt{sanitize} option using +\ipkgopt[description]{sanitize}\ipkgopt[symbol]{sanitize}\verb|sanitize={description=false,symbol=false}|, so +remember to protect fragile commands when defining acronyms. + +\item[dua]\ifmakedtx{\mbox{}\par}{} +The \pkgopt{dua} package option always displays the expanded +form and so may not be used with \pkgopt{footnote} or +\pkgopt{smallcaps}. Both first use and subsequent use displays the +entry in the form:\\[10pt] +\meta{long}\meta{insert}\\[10pt] +If the \pkgopt{description} option is also used, the \gloskey{name} +key is set to the long form, otherwise the \gloskey{name} key is +set to the short form and the \gloskey{description} key is set to +the long form. + +\item[\pkgopt{description}]\ifmakedtx{\mbox{}\par}{} +This option displays the entry on first use as:\\[10pt] +\meta{long}\meta{insert} (\cs{acronymfont}\marg{abbrv})\\[10pt] +while subsequent use displays the entry as:\\[10pt] +\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt] +Note also that if this package option is used, the \sty{glossaries} +package additionally implements the option +\ipkgopt[symbol]{sanitize}\verb|sanitize={symbol=false}|, so +remember to protect fragile commands when defining acronyms. + +\item[\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{} +This option displays the entry on first use as:\\[10pt] +\cs{acronymfont}\marg{abbrv}\meta{insert}\cs{footnote}\marg{long}\\[10pt] +while subsequent use displays the entry as:\\[10pt] +\cs{acronymfont}\marg{abbrv}\meta{insert} + +Note also that if this package option is used, the \sty{glossaries} +package additionally implements the option +\ipkgopt[description]{sanitize}\verb|sanitize={description=false}|, so +remember to protect fragile commands when defining acronyms. + +\item[\pkgopt{smallcaps}]\ifmakedtx{\mbox{}\par}{} +If neither the \pkgopt{footnote} nor \pkgopt{description} options +have been set, this option displays the entry on first use as:\\[10pt] +\meta{long}\meta{insert} (\cs{acronymfont}\marg{abbrv})\\[10pt] +while subsequent use displays the entry as:\\[10pt] +\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt] +where \cs{acronymfont} is set to \cs{textsc}. + +Note also that if this package option is used, the \sty{glossaries} +package additionally implements the option +\ipkgopt[symbol]{sanitize}\verb|sanitize={symbol=false}|, so +remember to protect fragile commands when defining acronyms. + +\item[None of the above]\ifmakedtx{\mbox{}\par}{} +If none of the package options \pkgopt{smallcaps}, \pkgopt{footnote} +or \pkgopt{description} are used, then on first use the entry is +displayed as:\\[10pt] +\meta{long} (\meta{abbrv})\meta{insert}\\[10pt] +while subsequent use displays the entry as:\\[10pt] +\cs{acronymfont}\marg{abbrv}\meta{insert}\\[10pt] +\meta{abbrv}\meta{insert} +\end{description} + +Recall from \ifmakedtx{\autoref{sec:glslink}}{\htmlref{earlier}{sec:glslink}} +that you can access the values of individual keys using commands +like \ics{glstext}, so it is possible to use these commands to +print just the long form or just the abbreviation without affecting +the flag that determines whether the entry has been used. However +the keys that store the long and short form vary depending on +the acronym style, so the \sty{glossaries} package provides +commands that are set according to the package options. These are +as follows: +\vspace{10pt}\par\noindent +\DescribeMacro{\acrshort} +\cs{acrshort}\oarg{options}\marg{label}\oarg{insert}\\ +\DescribeMacro{\Acrshort} +\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}\\ +\DescribeMacro{\ACRshort} +\cs{ACRshort}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +Print the abbreviated version with a hyperlink (if necessary) to the +relevant entry in the glossary. This is usually equivalent to +\ics{glstext} (or its uppercase variants) but may additionally +put the link text within the argument to \ics{acronymfont}. +\vspace{10pt}\par\noindent +\DescribeMacro{\acrlong} +\cs{acrlong}\oarg{options}\marg{label}\oarg{insert}\\ +\DescribeMacro{\Acrlong} +\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}\\ +\DescribeMacro{\ACRlong} +\cs{ACRlong}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +Print the long version with a hyperlink (if necessary) to the +relevant entry in the glossary. This is may be equivalent to +\ics{glsdesc}, \ics{glssymbol} or \ics{glsfirst} (or their uppercase +variants), depending on package options. +\vspace{10pt}\par\noindent +\DescribeMacro{\acrfull} +\cs{acrfull}\oarg{options}\marg{label}\oarg{insert}\\ +\DescribeMacro{\Acrfull} +\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert}\\ +\DescribeMacro{\ACRfull} +\cs{ACRfull}\oarg{options}\marg{label}\oarg{insert}\\[10pt] +Print the long version followed by the abbreviation in brackets +with a hyperlink (if necessary) to the +relevant entry in the glossary. + +Note that if you change the definition of \ics{newacronym}, you +may additionally need to change the above commands as well as +the changing way the text is displayed using \ics{defglsdisplay} +and \ics{defglsdisplayfirst}. + +\ifmakedtx{}{\toTop} + +\subsection{Unsetting and resetting entry flags} + +When using commands such as \ics{gls} it is possible that you may want +to use the value given by the \gloskey{first} key, even though you have +already used the glossary entry. Conversely, you may want to use the +value given by the \gloskey{text} key, even though you haven't used the +glossary entry. The former can be achieved by one of the following +commands:\\[10pt] +\DescribeMacro{\glsreset}\cs{glsreset}\marg{label}\\ +\DescribeMacro{\glslocalreset}\cs{glslocalreset}\marg{label}\\[10pt] +while the latter can be achieved by one of the following commands:\\[10pt] +\DescribeMacro{\glsunset}\cs{glsunset}\marg{label}\\ +\DescribeMacro{\glslocalunset}\cs{glslocalunset}\marg{label} +\\[10pt] +You can determine whether an entry has been used using:\\[10pt] +\DescribeMacro{\ifglsused} +\cs{ifglsused}\marg{label}\marg{true part}\marg{false part}\\[10pt] +where \meta{label} is the label of the required entry. If the +entry has been used, \meta{true part} will be done, otherwise +\meta{false part} will be done. +\ifmakedtx{}{\toTop} + +\subsection{Glossary Styles} +\label{sec:styles} +The \sty{glossaries} package comes with some pre-defined +glossary styles. These are as follows: +\begin{description} +\item[list] The \glostyle{list} style uses the \envname{description} +environment. The entry name is placed in the optional argument +of the \cs{item} command (so it will appear in bold by +default). The description follows, and then the associated number +list for that entry. + +\item[listgroup] The \glostyle{listgroup} style is like +\glostyle{list} but the glossary groups have headings. + +\item[listhypergroup] The \glostyle{listhypergroup} style is like +\glostyle{listgroup} but has a set of links to the glossary +groups. + +\item[altlist] The \glostyle{altlist} style is like \glostyle{list} +but the description is placed on the following line. + +\item[altlistgroup] The \glostyle{altlistgroup} style is like +\glostyle{altlist} but the glossary groups have headings. + +\item[altlisthypergroup] The \glostyle{altlisthypergroup} style is like +\glostyle{altlistgroup} but has a set of links to the glossary +groups. + +\item[listdotted] This style uses the \envname{description} +environment. Each entry starts with \verb|\item[]|, followed by the +name followed by a dotted line, followed by the description. Note that +this style ignores both the \term{number list} and the symbol. The +length \DescribeMacro{\glslistdottedwidth}\cs{glslistdottedwidth} +governs where the description should start.\footnote{This style was +supplied by Axel~Menzel.} + +\item[long] The \glostyle{long} style uses the \envname{longtable} +environment (defined by the \isty{longtable} package). It has two +columns: the first column contains the entry's name and the second +column contains the description followed by the \term{number list}. + +\item[longborder] The \glostyle{longborder} style is like +\glostyle{long} but has horizontal and vertical lines around it. + +\item[longheader] The \glostyle{longheader} style is like +\glostyle{long} but has a header row. + +\item[longheaderborder] The \glostyle{longheaderborder} style is +like \glostyle{longheader} but has horizontal and vertical lines +around it. + +\item[long3col] The \glostyle{long3col} style is like +\glostyle{long} but has three columns. The first column contains +the entry's name, the second column contains the description +and the third column contains the \term{number list}. + +\item[long3colborder] The \glostyle{long3colborder} style is like +the \glostyle{long3col} style but has horizontal and vertical +lines around it. + +\item[long3colheader] The \glostyle{long3colheader} style is like +\glostyle{long3col} but has a header row. + +\item[long3colheaderborder] The \glostyle{long3colheaderborder} style is +like \glostyle{long3colheader} but has horizontal and vertical lines +around it. + +\item[long4col] The \glostyle{long4col} style is like +\glostyle{long3col} but has an additional column in which the +entry's associated symbol appears. + +\item[long4colborder] The \glostyle{long4colborder} style is like +the \glostyle{long4col} style but has horizontal and vertical +lines around it. + +\item[long4colheader] The \glostyle{long4colheader} style is like +\glostyle{long4col} but has a header row. + +\item[long4colheaderborder] The \glostyle{long4colheaderborder} style is +like \glostyle{long4colheader} but has horizontal and vertical lines +around it. + +\item[super] The \glostyle{super} style uses the \envname{supertabular} +environment (defined by the \isty{supertabular} package). It has two +columns: the first column contains the entry's name and the second +column contains the description followed by the \term{number list}. + +\item[superborder] The \glostyle{superborder} style is like +\glostyle{super} but has horizontal and vertical lines around it. + +\item[superheader] The \glostyle{superheader} style is like +\glostyle{super} but has a header row. + +\item[superheaderborder] The \glostyle{superheaderborder} style is +like \glostyle{superheader} but has horizontal and vertical lines +around it. + +\item[super3col] The \glostyle{super3col} style is like +\glostyle{super} but has three columns. The first column contains +the entry's name, the second column contains the description +and the third column contains the \iterm{number list}. + +\item[super3colborder] The \glostyle{super3colborder} style is like +the \glostyle{super3col} style but has horizontal and vertical +lines around it. + +\item[super3colheader] The \glostyle{super3colheader} style is like +\glostyle{super3col} but has a header row. + +\item[super3colheaderborder] The \glostyle{super3colheaderborder} style +is like \glostyle{super3colheader} but has horizontal and vertical +lines around it. + +\item[super4col] The \glostyle{super4col} style is like +\glostyle{super3col} but has an additional column in which the +entry's associated symbol appears. + +\item[super4colborder] The \glostyle{super4colborder} style is like +the \glostyle{super4col} style but has horizontal and vertical +lines around it. + +\item[super4colheader] The \glostyle{super4colheader} style is like +\glostyle{super4col} but has a header row. + +\item[super4colheaderborder] The \glostyle{super4colheaderborder} style +is like \glostyle{super4colheader} but has horizontal and vertical +lines around it. + +\end{description} + +The glossary style can be set using the \pkgopt{style} package option +or using the \gloskey[printglossary]{style} key in the optional +argument to \ics{printglossary} or using the command:\\[10pt] +\DescribeMacro{\glossarystyle}\cs{glossarystyle}\marg{style-name}\\[10pt] + + \changes{1.03}{2007 July 4}{'glspostdescription added} +All the styles except for the three- and four-column styles and the +\glostyle{listdotted} style use the command +\DescribeMacro{\glspostdescription}\cs{glspostdescription} after the +description. This simply displays a full stop by default. To eliminate +this full stop (or replace it with something else, say a comma), you +will need to redefine \cs{glspostdescription} before the glossary is +displayed.\ifmakedtx{}{\toTop} + +\subsection{Defining your own glossary style} + +If the predefined styles don't fit your requirements, you can +define your own style using\DescribeMacro{\newglossarystyle}:\\[10pt] +\cs{newglossarystyle}\marg{name}\marg{definitions}\\[10pt] +where \meta{name} is the name of the new glossary style (to be +used in \cs{glossarystyle}). The second argument \meta{definitions}, +needs to redefine all of the following: + +\begin{description} +\item +\DescribeEnv{theglossary} +\envname{theglossary}\par\noindent +This environment defines how the main body of the glossary should +be typeset. Note that this does not include the section heading, +the glossary preamble (defined by \cs{glossarypreamble}) or the +glossary postamble (defined by \cs{glossarypostamble}.) For example, +the \glostyle{list} style uses the \envname{description} environment, +so the \envname{theglossary} environment is simply redefined to begin +and end the \envname{description} environment. + +\item +\DescribeMacro{\glossaryheader} +\cs{glossaryheader}\par\noindent +This macro indicates what to do at the start of the main body +of the glossary. Note that this is not the same as +\cs{glossarypreamble}, which should not be affected by changes in +the glossary style. The \glostyle{list} glossary style redefines +\cs{glossaryheader} to do nothing, whereas the \glostyle{longheader} +glossary style redefines \cs{glossaryheader} to do a header row. + +\item +\DescribeMacro{\glsgroupheading} +\cs{glsgroupheading}\marg{label}\par\noindent +This macro indicates what to do at the start of each logical block +within the main body of the glossary. The glossary is sub-divided into +twenty-eight logical blocks that are determined by the first character +of the \gloskey{sort} key (or \gloskey{name} key if the \gloskey{sort} +key is omitted). The sub-divisions are in the following order: symbols, +numbers, A, \ldots, Z. Note that the argument to \cs{glsgroupheading} +is a label \emph{not} the group title. The group title can be obtained +via \cs{glsgetgrouptitle}\marg{label}, and a navigation hypertarget can +be created using \cs{glsnavhypertarget}\marg{label}. Most of the +predefined glossary styles redefine \cs{glsgroupheading} to simply +ignore its argument. The \glostyle{listhypergroup} style redefines +\cs{glsgroupheading} as follows: +\begin{verbatim} +\renewcommand*{\glsgroupheading}[1]{% +\item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]} +\end{verbatim} +See also \cs{glsgroupskip} below. (Note that command definitions within +\cs{newglossarystyle} must use \verb|##1| etc instead of \verb|#1| etc.) + +\item +\DescribeMacro{\glsgroupskip} +\cs{glsgroupskip}\par\noindent +This macro determines what to do after one logical group but before +the header for the next logical group. The \glostyle{list} glossary +style simply redefines \cs{glsgroupskip} to be \cs{indexspace}. + +\item +\DescribeMacro{\glossaryentryfield} +\cs{glossaryentryfield}\marg{label}\marg{formatted +name}\marg{description}\marg{symbol} +\marg{number list}\par\noindent +This macro indicates what to do for a given glossary entry. +Note that \meta{formatted name} will always be in the form +\cs{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 \cs{newglossaryentry} or \cs{newacronym}. +Each time you use a glossary entry it creates a +link\footnote{if the document doesn't have hyperlinks enabled +\cs{@glslink} ignores the label and simply typesets the text.} +using \cs{@glslink}\marg{label}\marg{text} with the label +\texttt{glo:}\meta{label}. Your +new glossary style must therefore redefine \cs{glossaryentryfield} +so that it uses \cs{@glstarget}\verb|{|\texttt{glo:}\meta{label}\verb|}|\marg{text} +to ensure the hyperlinks function correctly.\footnote{again, if the +document doesn't support hyperlinks, \cs{@glstarget} will ignore +the label, and just typeset the text.} For example, the +\glostyle{list} style defines \cs{glossaryentryfield} as follows: +\begin{verbatim} +\renewcommand*{\glossaryentryfield}[5]{% +\item[\@glstarget{glo:##1}{##2}] ##3\glspostdescription\space ##5} +\end{verbatim} + +Note also that \meta{number list} will always be of the form\\[10pt] +\cs{glossaryentrynumbers}\{\cs{relax}\\ +\cs{setentrycounter}\marg{counter name}\cs{glsnumberformat}\marg{number(s)}\}\\[10pt] +where \meta{number(s)} +may contain \cs{delimN} (to delimit individual numbers) and/or +\cs{delimR} (to indicate a range of numbers). There may be +multiple occurrences of +\cs{setentrycounter}\marg{counter name}\cs{glsnumberformat}\marg{number(s)}, but note +that the entire number list is enclosed within the argument +to \ics{glossaryentrynumbers}. The user can redefine this to change +the way the entire number list is formatted, regardless of +the glossary style. However the most common use of +\cs{glossaryentrynumbers} is to provide a means of suppressing the +number list altogether. (In fact, the \pkgopt{nonumberlist} option +redefines \cs{glossaryentrynumbers} to ignore its argument.) +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. +\end{description}\ifmakedtx{}{\toTop} + +\subsubsection{Example: creating a completely new style} + +If you want a completely new style, you will need to redefine all +of the commands and environment listed above. You also need to +take care when using internal commands (commands whose name +contain the @ symbol). These should either be used in a \texttt{.sty} +file or must be placed within \cs{makeatletter} and \cs{makeatother}. + +For example, suppose you want each entry to start with a bullet point. +This means that the glossary should be placed in the \envname{itemize} +environment, so \envname{theglossary} should start and end that +environment. Let's also suppose that you don't want anything between +the glossary groups (so \cs{glsgroupheading} and \cs{glsgroupskip} +should do nothing) and suppose you don't want anything to appear +immediately after \verb|\begin{theglossary}| (so \cs{glossaryheader} +should do nothing). In addition, let's suppose the symbol should +appear in brackets after the name, followed by the description and +last of all the \term{number list} should appear within square brackets +at the end. Then you can create this new glossary style, called, say, +\texttt{mylist}, as follows: +\begin{verbatim} + \newglossarystyle{mylist}{% + % put the glossary in the itemize environment: + \renewenvironment{theglossary}{\begin{itemize}}{\end{itemize}}% + % have nothing after \begin{theglossary}: + \renewcommand*{\glossaryheader}{}% + % have nothing between glossary groups: + \renewcommand*{\glsgroupheading}[1]{}% + \renewcommand*{\glsgroupskip}{}% + % set how each entry should appear: + \renewcommand*{\glossaryentryfield}[5]{% + \item % bullet point + \@glstarget{glo:##1}{##2}% the entry name + \space (##4)% the symbol in brackets + \space ##3% the description + \space [##5]% the number list in square brackets + }% + } +\end{verbatim} +\ifmakedtx{}{\toTop} + +\subsubsection{Example: creating a new glossary style based on an +existing style} + +\changes{1.11}{2008 March 1}{Fixed error in manual (glossary style +is set using 'glossarystyle not 'setglossarystyle)}% +If you want to define a new style that is a slightly modified +version of an existing style, you can use \cs{glossarystyle} +within the second argument of \cs{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 +vertical space created by \cs{indexspace} between groups, then you +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 +\renewcommand{\glsgroupskip}{}% make nothing happen between groups +} +\end{verbatim} +\ifmakedtx{}{\toTop} + + \StopEventually{\clearpage\phantomsection\addcontentsline{toc}{section}{Index}\PrintIndex} + +\ifmakedtx{}{\printindex\toTop} + +\end{document} |