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 | 941 |
1 files changed, 327 insertions, 614 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex index 9791f8f8b72..403a5d3b9a7 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex @@ -27,7 +27,7 @@ \makeatother \RecordChanges \PageIndex -\CheckSum{8209} +\CheckSum{8706} \CodelineNumbered \newcommand*{\termdef}[1]{\emph{#1}\iterm{#1}} \newcommand*{\term}[1]{#1\iterm{#1}} @@ -131,7 +131,7 @@ \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{glossaries.sty v 1.2: \LaTeXe\ Package to Assist Generating Glossaries} + \title{glossaries.sty v 2.01: \LaTeXe\ Package to Assist Generating Glossaries} \author{Nicola L.C. Talbot\\[10pt] School of Computing Sciences\\ University of East Anglia\\ @@ -139,7 +139,7 @@ Norwich. Norfolk\\ NR4 7TJ. United Kingdom.\\ \url{http://theoval.cmp.uea.ac.uk/~nlct/}} - \date{16th April 2009} + \date{30th May 2009} \maketitle \tableofcontents @@ -161,9 +161,18 @@ via \ics{glssee} (or the \gloskey{see} key)} in the document will be added to the glossary. \textbf{This package replaces the \isty{glossary} package which is -now obsolete. Please see the file -\ifmakedtx{\url{glossary2glossaries.pdf}}{% -\url{glossary2glossaries.html}} for assistance in upgrading.} +now obsolete.} Please see +\ifmakedtx{the document \dq{Upgrading from the glossary package to +the glossaries package} (\href{glossary2glossaries.pdf}{glossary2glossaries.pdf})}{\htmladdnormallink{Upgrading from the glossary package +to the glossaries package}{glossary2glossaries.html}} +for assistance in upgrading. + +One of the strengths of this package is its flexibility, however +the drawback of this is the necessity of having a large manual +that can cover all the various settings. If you are daunted by the +size of the manual, try starting off with the much shorter +\ifmakedtx{guide for beginners (\href{glossariesbegin.pdf}{glossariesbegin.pdf})}{% +\htmladdnormallink{guide for beginners}{glossariesbegin.html}}. \begin{important} The \sty{glossaries} package comes with a @@ -179,17 +188,9 @@ Associated Glossary Files}{sec:makeglossaries}} for further details. \end{important} -One of the strengths of this package is its flexibility, however -the drawback of this is the necessity of having a large manual -that can cover all the various settings. The documentation is -therefore structured as follows: +This manual is structured as follows: \begin{itemize} -\item \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 creating a basic glossary, without -having to read through lengthy descriptions. - -\item \ifmakedtx{\autoref{sec:overview}}{\htmlref{Overview of User Commands}{sec:overview}} +\item \ifmakedtx{\autoref{sec:overview}}{\htmlref{Overview of Main User Commands}{sec:overview}} gives an overview of the main user commands and their syntax. \item \ifmakedtx{\autoref{sec:mfirstuc}}{\htmlref{Mfirstuc}{sec:mfirstuc}} @@ -197,11 +198,17 @@ describes the associated \sty{mfirstuc} package. \ifmakedtx{\item \autoref{sec:code} contains the documented source code for those who -want to know more about how the package works. +want to know more about how the package works. This describes more +advanced commands, such as determining if an entry or a glossary +exists and commands that iterate through defined terms or glossaries. \item \autoref{sec:code:mfirstuc} contains the documented code for the \sty{mfirstuc} package.}{} \end{itemize} +\ifmakedtx{}{The \htmladdnormallink{PDF version}{glossaries.pdf} of +this manual also describes more advanced commands in the documented +code section (such as determining if an entry or a glossary exists +and commands that iterate through defined terms or glossaries).} \noindent The remainder of this introductory section covers the following: @@ -242,9 +249,10 @@ This should display the full pathname of the file see if it contains the \texttt{samples} subdirectory. If you can't find the sample files, they are available in the -\texttt{doc/latex/glossaries/samples/} subdirectory of the +subdirectory \texttt{doc/latex/glossaries/samples/} in the \texttt{glossaries.tds.zip} archive which can be downloaded from -CTAN. +\ifmakedtx{\href{http://tug.ctan.org/tex-archive/macros/latex/contrib/glossaries/}{CTAN}}{\htmladdnormallink{CTAN}{http://tug.ctan.org/tex-archive/macros/latex/contrib/glossaries/}}. + The sample documents are as follows: \begin{description} @@ -530,7 +538,7 @@ makeglossaries sampleutf8 latex sampleutf8 \end{verbatim} you will see that the entries that start with a non-Latin character -now appear in the symbols group, and the word \dq{manœuvre} is now +now appear in the symbols group, and the word \dq{man\oe uvre} is now after \dq{manor} instead of before it. If you are unable to use \appname{makeglossaries}, the call to \appname{makeindex} is as follows (no line breaks): @@ -544,8 +552,8 @@ uses the experimental \isty{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 \sty{glossaries-accsupp} package can be found in -\ifmakedtx{\autoref{sec:accsupp}}{\htmlref{\dq{Accessibility -Support}{sec:accsupp}}}. +\ifmakedtx{\autoref{sec:accsupp}}{\htmlref{\dq{Accessibility Support}}{sec:accsupp}}. + \end{description} \ifmakedtx{}{\toTop} @@ -570,7 +578,7 @@ If you want to use \appname{xindy}, remember to use the \end{verbatim} \begin{important} -If you use an accented or non-Latin character at the start of +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 (e.g.\ \ics{Gls}) due to expansion issues. For example: @@ -822,8 +830,7 @@ use \texttt{-C} \meta{code} The \appname{makeglossaries} script picks up the relevant information from the auxiliary (\filetype{.aux}) file and will either call \appname{xindy} or \appname{makeindex}, -depending on whether the indexing style file ends with -\filetype{.xdy} or \filetype{.ist}. Therefore, you only need to +depending on the supplied information. Therefore, you only need to pass the document's name without the extension to \appname{makeglossaries}. For example, if your document is called \texttt{myDoc.tex}, @@ -959,6 +966,52 @@ you use \appname{makeindex} explicitly instead of using \tableref{tab:makeglossariesCmds}. \ifmakedtx{}{\toTop} +\subsubsection{Note to Front-End and Script Developers} + +The information needed to determine whether to use \appname{xindy} +or \appname{makeindex} and the information needed to call those +applications is stored in the auxiliary file. This information can +be gathered by a front-end, editor or script to make the glossaries +where appropriate. This section describes how the information is +stored in the auxiliary file. + +The file extensions used by each defined glossary are given by\\[10pt] +\cs{@newglossary}\marg{label}\marg{log}\marg{out-ext}\marg{in-ext}\\[10pt] +where \meta{in-ext} is the extension of the \emph{indexing +application's} input file (the output file from the \sty{glossaries} +package's point of view), \meta{out-ext} is the extension of the +\emph{indexing application's} output file (the input file from +the \sty{glossaries} package's point of view) and \meta{log} is the +extension of the indexing application's transcript file. The label +for the glossary is also given for information purposes only, but +is not required by the indexing applications. For example, the +information for the main glossary is written as: +\begin{verbatim} +\@newglossary{main}{glg}{gls}{glo} +\end{verbatim} + +The indexing application's style file is specified by\\[10pt] +\cs{@istfilename}\marg{filename}\\[10pt] +The file extension indicates whether to use \appname{makeindex} +(\filetype{.ist}) or \appname{xindy} (\filetype{.xdy}). Note that +the glossary information is formatted differently depending on +which indexing application is supposed to be used, so it's +important to call the correct one. + +Word or letter ordering is specified by:\\[10pt] +\cs{@glsorder}\marg{order}\\[10pt] +where \meta{order} can be either \texttt{word} or \texttt{letter}. + +If \appname{xindy} should be used, the language and code page +for each glossary is specified by\\[10pt] +\cs{@xdylanguage}\marg{label}\marg{language}\\ +\cs{@gls@codepage}\marg{label}\marg{code}\\[10pt] +where \meta{label} identifies the glossary, \meta{language} is +the root language (e.g.\ \texttt{english}) and \meta{code} +is the encoding (e.g.\ \texttt{utf8}). These commands are omitted +if \appname{makeindex} should be used. +\ifmakedtx{}{\toTop} + \subsection{Troubleshooting} \label{sec:trouble} @@ -1095,8 +1148,8 @@ then run \LaTeX\ on your document again. If you want the glossaries to appear in the table of contents, you will need an extra \LaTeX\ run. If any of your entries cross-reference an entry that's not referenced in the main body of the document, you will need to -run \appname{makeglossaries} after the second \LaTeX\ run, followed -by another \LaTeX\ run. +\ifmakedtx{run \appname{makeglossaries} (see \autoref{sec:makeglossaries})}{\htmlref{run \appname{makeglossaries}}{sec:makeglossaries}} +after the second \LaTeX\ run, followed by another \LaTeX\ run. \end{itemize} Check the log files (\filetype{.log}, \filetype{.glg} etc) for any @@ -1105,7 +1158,7 @@ warnings. \item \textbf{Q.} It is possible to change the rules used to sort the glossary entries? -\item \textbf{A.} If it's for an individual entry, then you can +\textbf{A.} If it's for an individual entry, then you can use the entry's \gloskey{sort} key to sort it according to a different term. If it's for the entire alphabet, then you will need to use \appname{xindy} (instead of \appname{makeindex}) and use an @@ -1120,558 +1173,7 @@ site. \end{enumerate} \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. However it is recommended that you read -\ifmakedtx{\autoref{sec:overview}}{\htmlref{the overview section}{sec:overview}} -for additional commands and advice not listed here. There are -also some sample files to help you get started, listed in -\ifmakedtx{\autoref{sec:samples}}{\htmlref{Sample -Documents}{sec:samples}}. The following is a minimal example: -\begin{verbatim} - \documentclass{article} - - % Load hyperref before glossaries - \usepackage[colorlinks]{hyperref} - \usepackage[acronym, % make a separate list of acronyms - toc % put the glossaries into the table of contents - ]{glossaries} - - % Write glossary entries to external file so that they - % can be sorted and collated by another application. - \makeglossaries - - % Define an entry whose label is `xample': - \newglossaryentry{xample}% unique label identifying this entry - {% Define the attributes for this entry: - name=sample,% the name or term begin defined - description={a sample entry}% a description of this entry - } - - % Define an acronym whose label is `ca': - \newacronym{ca}% label - {CA}% acronym - {Contrived Acronym}% expanded form - - \begin{document} - \tableofcontents - - A \gls{xample} entry and a \gls{ca}. - - \printglossaries - \end{document} -\end{verbatim} -\ifmakedtx{}{\toTop} - -\subsection{Package Order} -Load \sty{glossaries} \emph{after} \isty{hyperref}: -\begin{verbatim} -\usepackage{hyperref} -\usepackage{glossaries} -\end{verbatim} -Similarly for the \isty{html} package: -\begin{verbatim} -\usepackage{html} -\usepackage{glossaries} -\end{verbatim} -Likewise for \isty{babel} and \isty{translator}. - -Note that if you are using the \isty{hyperref} package and the -glossaries are in chapters, you may need to redefine -\ics{glsclearpage} to do \ics{clearpage} instead of -\cs{cleardoublepage} to prevent an unwanted blank page appearing -before the glossary: -\begin{verbatim} -\renewcommand*{\glsclearpage}{\clearpage} -\end{verbatim} -\ifmakedtx{}{\toTop} - -\subsection{Displaying Glossaries} - -Always use \ics{makeglossaries} if you want the glossary -entries to be written to the glossary file: -\begin{verbatim} -\usepackage{glossaries} -\makeglossaries -\end{verbatim} -If you don't use \ics{makeglossaries}, your glossaries will -not appear in the document! - -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. -See \ifmakedtx{\autoref{sec:printglossary}}{\htmlref{Displaying a glossary}{sec:printglossary} in the main overview section} -for further details. - -To add the glossaries to the table of contents use the -\pkgopt{toc} package option: -\begin{verbatim} -\usepackage[toc]{glossaries} -\end{verbatim} -This will require an extra \LaTeX\ run. Note that if the table -of contents affects the subsequent page numbering (i.e.\ the -page numbers are not reset after the table of contents) then you -may need to rerun \appname{makeglossaries} and \LaTeX. - -The font used to display the entry name in the glossary -is governed by \ics{glsnamefont}. This can be redefined -as required. For example, to make the entry names appear -in a medium sans-serif font do: -\begin{verbatim} -\renewcommand{\glsnamefont}[1]{\textsf{\mdseries #1}} -\end{verbatim} -Note that the list-like glossary styles place the entry name in -the optional argument to \ics{item}, so they will -appear in bold, unless you redefine \ics{glsnamefont} to counteract -the bold font. Similarly, the tree-like styles display the -entry name in bold. - -Glossary styles can be set using the \pkgopt{style} -package option. For example: -\begin{verbatim} -\usepackage[style=long3col]{glossaries} -\end{verbatim} -or using \ics{glossarystyle}\marg{style}. For example: -\begin{verbatim} -\glossarystyle{altlist} -\end{verbatim} -The predefined glossary styles provided by the \sty{glossaries} -bundle are listed in \ifmakedtx{\autoref{sec:styles}}{\htmlref{{Glossary -Styles}}{sec:styles}}. - -Each entry in the glossary has an associated list of numbers -indicating whereabouts in the document that entry has been used. -The number lists can be suppressed using package option -\pkgopt{nonumberlist}: -\begin{verbatim} -\usepackage[nonumberlist]{glossaries} -\end{verbatim} -See \ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number lists}{sec:numberlists}} -for further details about number lists. - -If your pages have a hyphen compositor (i.e.\ your page -numbers appear in the form 2-1), use \ics{glsSetCompositor} -\emph{before} \ics{makeglossaries}: -\begin{verbatim} -\documentclass{article} -\usepackage{glossaries} -\glsSetCompositor{-} -\makeglossaries -\end{verbatim} - -By default, the glossary will appear in an unnumbered -chapter if chapters are defined, otherwise in an unnumbered -section. This can be changed using the \pkgopt{section} package -option. For example, to make the glossaries appear in an unnumbered -section, even if chapters are defined, do: -\begin{verbatim} -\usepackage[section]{glossaries} -\end{verbatim} -Other sectional units can also be specified as -\pkgopt{section}=\meta{value}. For example, to make the glossaries -appear in unnumbered subsections: -\begin{verbatim} -\usepackage[section=subsection]{glossaries} -\end{verbatim} - -When you have created your document, run \LaTeX\ on it, -then the Perl script \appname{makeglossaries}, then run \LaTeX\ -on it again: -\begin{verbatim} -latex myfile -makeglossaries myfile -latex myfile -\end{verbatim} -(You need to run \LaTeX\ again if you have used the \pkgopt{toc} -package option. You may also need an extra \appname{makeglossaries} -run and another \LaTeX\ run if an entry is only referenced in the -glossary, or if including the glossary has caused the -number lists\iterm{number list} to change.) - -If you use Windows, there is a batch file called -\texttt{makeglossaries.bat} which you can use, but you will -still need Perl installed. Alternatively, you can call -\appname{makeindex} directly. See -\ifmakedtx{\autoref{sec:makeglossaries}}{\htmlref{Generating the -Associated Glossary Files}{sec:makeglossaries}} for -further details. - -If you want to use \appname{xindy} instead of -\appname{makeindex}, you must specify it in the package option: -\begin{verbatim} -\usepackage[xindy]{glossaries} -\end{verbatim} -See -\ifmakedtx{\autoref{sec:makeglossaries}}{\htmlref{Generating the -Associated Glossary Files}{sec:makeglossaries}} for -further details. -\ifmakedtx{}{\toTop} - -\subsection{Defining Additional Glossaries} - -New glossaries can be defined using:\par -\ics{newglossary}\oarg{log-ext}% -\marg{label}\marg{in-ext}\marg{out-ext}% -\marg{title}\par where \meta{label} is an identifying label, -\meta{in-ext} is the extension of the file to be created -by \appname{makeindex} or \appname{xindy} (called by -\appname{makeglossaries}), -\meta{out-ext} is the extension of the file to be read by -\appname{makeindex} or \appname{xindy} and \meta{title} is the title for this -new glossary. The first optional argument \meta{log-ext} specifies -the extension of the \appname{makeindex} or \appname{xindy} -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} or \appname{xindy} 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. - -Any new glossaries must be defined before -\ics{makeglossaries}: -\begin{verbatim} -\usepackage{glossaries} -\newglossary{notation}{not}{ntn}{Notation} -\makeglossaries -\end{verbatim} - -If you use the \pkgopt{acronym} package option, the -\sty{glossaries} package -will automatically create a new glossary type labelled -\texttt{acronym}: -\begin{verbatim} -\usepackage[acronym]{glossaries} -\end{verbatim} -\ifmakedtx{}{\toTop} - -\subsection{Defining New Entries} - -A glossary term is defined using:\par -\ics{newglossaryentry}\marg{label}\marg{key-val list}\par -The \meta{key-val list} must at least contain a \gloskey{name} -key and a \gloskey{description} key. -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. - -Only those terms that have actually been used in the -document will be placed in the glossary. If you have defined -a term that doesn't appear in the glossary, then it means -you haven't used it in the text (either via \ics{glslink} -or \ics{gls} and related commands or via \ics{glsadd} -or \ics{glsaddall} or via \ics{glssee}). - -If you have multiple glossaries, use the \gloskey{type} -key to specify in which glossary the entry belongs. For example: -\begin{verbatim} -\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. - -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} - -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} -See \ifmakedtx{\autoref{sec:styles}}{\htmlref{Glossary -Styles}{sec:styles}} for a list of predefined glossary -styles. - -See \ifmakedtx{\autoref{sec:newglosentry}}{\htmlref{Defining Glossary Entries}{sec:newglosentry} in the main overview section} -for further details. -\ifmakedtx{}{\toTop} - -\subsection{Defining Sub-Entries} -To define a sub-entry, use the \gloskey{parent} key. For -example: -\begin{verbatim} -\newglossaryentry{fruit}{name={fruit}, % parent entry -description={tree product that contains seeds}} - -\newglossaryentry{apple}{name={apple}, % sub-entry -description={firm, round fruit}, -parent=fruit} -\end{verbatim} - -Sub-entries may have the same name as the parent entry: -\begin{verbatim} -\newglossaryentry{glossary}{name=glossary, % parent entry -description={\nopostdesc}, -plural={glossaries}} - -\newglossaryentry{glossarylist}{% first child entry -description={1) list of technical words}, -sort={1}, -parent={glossary}} - -\newglossaryentry{glossarycol}{% second child entry -description={2) collection of glosses}, -sort={2}, -parent={glossary}} -\end{verbatim} -Note that in this instance the \gloskey{name} key is not -required for the child entries, but the \gloskey{sort} key is -needed to sort the sub-entries. The parent entry has no -description, so the description terminator is suppressed using -\ics{nopostdesc}. - -See \ifmakedtx{\autoref{sec:subentries}}{\htmlref{Sub-Entries}{sec:subentries}} for -further details. -\ifmakedtx{}{\toTop} - -\subsection{Changing the Sort Order} -To change the sorting order, use the \gloskey{sort} key. -For example: -\begin{verbatim} -\newglossaryentry{tex}{name={\TeX}, -description={A typesetting language}, -sort=tex} -\end{verbatim} -This will put the entry in the \dq{T} group (entries starting with -the letter \dq{t} or \dq{T}) rather than the -\dq{symbols} group (entries starting with a symbol). -Similarly, the following example puts the entry in the \dq{U} -group instead of the \dq{symbol} group. -\begin{verbatim} -\newglossaryentry{universal}{name={\ensuremath{\mathcal{U}}}, -description=The universal set, -sort=U} -\end{verbatim} - -Unlike the old \sty{glossary} package, you don't need to escape -\appname{makeindex}'s special characters: -\begin{verbatim} -\newglossaryentry{quote}{name={"}, -description={Double quote character}} - -\newglossaryentry{exclam}{name={!}, -description={Exclamation mark}} - -\newacronym{rna}{RNA}{ribonukleins\"aure} -\end{verbatim} - -\ifmakedtx{}{\toTop} - -\subsection{Accented or Non-Latin Characters} -If the entry name starts with an accented letter or -non-Latin character, you will need to group the first letter -(otherwise it will cause a problem for commands like \ics{Gls} and -\ics{Glspl}): -\begin{verbatim} -\newglossaryentry{elite}{name={{\'e}lite}, -sort=elite, -description={select group or class}} -\end{verbatim} -Likewise with commands such as \cs{ae} and \cs{oe}: -\begin{verbatim} -\newglossaryentry{oesophagus}{% -name={{\oe}sophagus}, -sort=oesophagus, -description={canal from mouth to stomach}} -\end{verbatim} - -If you use \appname{xindy}, you can specify the accented -or non-Latin character directly (in combination with the -\isty{inputenc} and \isty{fontenc} packages) but you still -need to group the first letter (otherwise it will cause a -problem for commands like \ics{Gls} and \ics{Glspl} due to -expansion issues): -\begin{verbatim} -\newglossaryentry{elite}{name={{é}lite}, -description={select group or class}} -\end{verbatim} -Note that in this case the \gloskey{sort} key is not required -as \appname{xindy} knows how to sort the letter \'e. -\ifmakedtx{}{\toTop} - -\subsection{Cross-Referencing Entries} -You can cross-reference an entry using the -\gloskey{see} key when you define it. For example, suppose -you have defined an entry whose label is \texttt{taylorstheorem}, -then you can cross-reference it: -\begin{verbatim} -\newglossaryentry{maclaurinseries}{name={Maclaurin series}, -description={Series expansion}, -see={taylorstheorem}} -\end{verbatim} -Alternatively, you can use \ics{glssee} after you have defined -the entry: -\begin{verbatim} -\glssee{maclaurinseries}{taylorstheorem} -\end{verbatim} -(The final argument may be a comma-separated list of labels.) -The \dq{see} tag may be overridden for a given entry: -\begin{verbatim} -\glssee[see also]{maclaurinseries}{taylorstheorem} -\end{verbatim} -or it can be changed for all entries by redefining \ics{seename}. -\ifmakedtx{}{\toTop} - -\subsection{Plurals} -Plural forms are assumed to be the singular form with an -\dq{s} appended, unless otherwise specified. To specify an -irregular plural, use the \gloskey{plural} key. For example: -\begin{verbatim} -\newglossaryentry{matrix}{name=matrix, -description=rectangular array of quantities, -plural=matrices} -\end{verbatim} - -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. -\ifmakedtx{}{\toTop} - -\subsection{Displaying Terms in the Document} -In the document use \ics{gls}\marg{label} -to use a term that has already been defined with -\ics{newglossaryentry} (this will also enter the term into -the associated glossary output file). For example: -\begin{verbatim} -A \gls{singmtx} is a matrix with a zero determinant. -\end{verbatim} - -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} - -Additional text can be appended to the link using the -end optional argument. For example, to form the possessive: -\begin{verbatim} -The \gls{singmtx}['s] dimensions \ldots -\end{verbatim} -See \ifmakedtx{\autoref{sec:glslink}}{\htmlref{Links to Glossary Entries}{sec:glslink}} -for further details. - -Entries can be added to the glossary without producing -any text using \ics{glsadd}\marg{label} or -\ics{glsaddall}. For example -\begin{verbatim} -\glsadd{singmtx} -\end{verbatim} -will add a line to the -glossary file for the specified term, but will not produce -any text where the command occurs. - -A number range can be entered using \verb|format=(| and -\verb"format=)" to mark the beginning and ending of the -range. For example: -\begin{verbatim} - \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 or \appname{xindy}'s \texttt{:open-range} and -\texttt{:close-range} tags. -\ifmakedtx{}{\toTop} - -\subsection{Acronyms} -The way the term appears on \firstuse\ can be different -to the way it appears subsequently: -\begin{verbatim} -\newglossaryentry{singmtx}{name=Singular Matrix, -description=A matrix with a zero determinant, -first=singular matrix (SM), -text=SM, -firstplural=singular matrices (SMs)} -\end{verbatim} -In this example, the entry name appears as \dq{Singular Matrix} in -the glossary, and in the text it appears as \dq{singular matrix (SM)} -or \dq{singular matrices (SMs)} the first time the entry is used, -and subsequently appears as \dq{SM} or \dq{SMs}. - -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.) - -You can reset an acronym with \ics{glsreset}\marg{label} so that the -next occurrence displays the long form with the acronym in brackets -as though it hadn't been used. To do this for all defined -terms, use \ics{glsresetall}. See -\ifmakedtx{\autoref{sec:glsunset}}{\htmlref{Unsetting and Resetting Entry Flags}{sec:glsunset}} -for further details. -\ifmakedtx{}{\toTop} - -\section{Overview of User Commands}\label{sec:overview} +\section{Overview of Main User Commands}\label{sec:overview} \changes{1.02}{2007 May 25}{added overview section} \subsection{Package Options} @@ -1705,6 +1207,15 @@ 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. +\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 above or via +\ics{newglossary} described in +\ifmakedtx{\autoref{sec:newglossary}}{\htmlref{Defining New +Glossaries}{sec:newglossary}}). + + \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, @@ -1841,7 +1352,8 @@ lists\iterm{number list}. 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 +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. \ifmakedtx{(See \autoref{sec:pkgopt} and \autoref{sec:newentry} for @@ -1852,6 +1364,8 @@ further details.)}{} For example, to switch off the sanitization for the \usepackage[sanitize={name=false,description=false,% symbol=true}]{glossaries} \end{verbatim} +You can use \pkgopt[none]{sanitize} as a shortcut for\newline +\pkgoptni{sanitize=\{name=false,description=false,symbol=false\}}. \begin{important}% \textbf{Note}: this sanitization only applies to the \gloskey{name}, @@ -1926,6 +1440,9 @@ for further details on using \appname{xindy} with the is word ordering. Note that this option has no effect if you don't use \appname{makeglossaries}. +\item[\pkgopt{nowarn}] This suppresses all warnings generated by +the \sty{glossaries} package. + \end{description}\ifmakedtx{}{\toTop} \subsection{Defining Glossary Entries} @@ -2276,8 +1793,7 @@ have different plurals, they will need to be specified. For example: \newglossaryentry{bravo}{name={bravo}, description={\nopostdesc}} -\newglossaryentry{bravocry}{description={1) cry of approval -(pl.\ bravos)}, +\newglossaryentry{bravocry}{description={1) cry of approval (pl.\ bravos)}, sort={1}, plural={bravos}, parent=bravo} @@ -2478,9 +1994,10 @@ will place \cs{glstextformat}\marg{text} in the document at that point and add a line into the associated glossary file for the glossary entry given by \meta{label}. If hyperlinks are supported, \meta{text} will be a hyperlink to the relevant line in the -glossary. The optional argument \meta{options} must be a -\meta{key}=\meta{value} list which can take any of the following -keys: +glossary. (Note that this command doesn't affect the \firstuseflag: +use \ics{glsdisp} instead.) 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 @@ -2585,7 +2102,9 @@ value is \texttt{hyper=true}. 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}. +\texttt{hyper=false}. Similarly, all the following commands +described in this section also have a starred version that disables +the hyperlink. \DescribeMacro{\gls} The command:\\[10pt] @@ -2635,12 +2154,13 @@ Note that \cs{glslink} doesn't use or affect the \firstuseflag, nor does it use \ics{glsdisplay} or \ics{glsdisplayfirst} (see \ifmakedtx{\autoref{sec:glsdisplay}}{\htmlref{later}{sec:glsdisplay}}). Instead, you can use:\\[10pt] -\DescribeMacro{glsdisp} +\DescribeMacro{\glsdisp} \cs{glsdisp}\oarg{options}\marg{label}\marg{link text}\\[10pt] This behaves in the same way as \cs{gls}, except that it uses \meta{link text} instead of the value of the \gloskey{first} or \gloskey{text} key. (Note that this command always sets -\meta{insert} to nothing.) +\meta{insert} to nothing.) This command affects the \firstuseflag, +and uses \ics{glsdisplay} or \ics{glsdisplayfirst}. \DescribeMacro{\glstext}The command:\\[10pt] \cs{glstext}\oarg{options}\marg{label}\oarg{insert}\\[10pt] @@ -2826,8 +2346,8 @@ 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 the commands \cs{gls}, \cs{glspl} and their -uppercase variants. If you only +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\\[10pt] \DescribeMacro{\defglsdisplay}\cs{defglsdisplay}\oarg{type}\marg{definition}\\[10pt] @@ -2841,7 +2361,7 @@ the first (which is optional) is the glossary's label\footnote{\texttt{main} for 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 +\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 @@ -3461,7 +2981,8 @@ 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 +so it can be identified by the label \texttt{main} (unless the +\pkgopt{nomain} package option is used). Using the \pkgopt{acronym} package option is equivalent to: \begin{verbatim} \newglossary[alg]{acronym}{acr}{acn}{\acronymname} @@ -4080,13 +3601,13 @@ be displayed if it has been defined.} \ttfamily sublistdotted & 1 & & \\ \ttfamily list* & 1 & \tick & \\ \ttfamily altlist* & 1 & \tick & \\ -\ttfamily long3col* & 1 & \tick & \\ +\ttfamily long*3col* & 1 & \tick & \\ \ttfamily long4col* & 1 & \tick & \tick \\ -\ttfamily altlong4col* & 1 & \tick & \tick \\ +\ttfamily altlong*4col* & 1 & \tick & \tick \\ \ttfamily long* & 1 & \tick & \\ -\ttfamily super3col* & 1 & \tick & \\ +\ttfamily super*3col* & 1 & \tick & \\ \ttfamily super4col* & 1 & \tick & \tick \\ -\ttfamily altsuper4col* & 1 & \tick & \tick \\ +\ttfamily altsuper*4col* & 1 & \tick & \tick \\ \ttfamily super* & 1 & \tick & \\ \ttfamily index* & 2 & & \tick\\ \ttfamily treenoname* & --- & \tick & \tick\\ @@ -4096,17 +3617,21 @@ be displayed if it has been defined.} \par \end{table} -The glossary style can be set using the \pkgopt{style} package option -or using the \gloskey[printglossary]{style} key in the optional +The glossary style can be set 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] +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 +is automatically loaded by the \sty{glossaries} package. + The tabular-like styles that allow multi-line descriptions and page lists use the length \DescribeMacro{\glsdescwidth}\cs{glsdescwidth} to set the width of the description column and the length \DescribeMacro{\glspagelistwidth}\cs{glspagelistwidth} to set the width of the page list column.\footnote{these lengths will not be available if you use both the \pkgopt{nolong} and \pkgopt{nosuper} -package options or if you use the \pkgopt{nostyles} package option.} +package options or if you use the \pkgopt{nostyles} package option +unless you explicitly load the relevant package.} These will need to be changed using \cs{setlength} if the glossary is too wide. Note that the \glostyle{long4col} and \glostyle{super4col} styles (and their header and border variations) @@ -4148,7 +3673,7 @@ All the styles except for the three- and four-column styles and the \glostyle{listdotted} style use the command \DescribeMacro{\glspostdescription}\cs{glspostdescription} after the description. This simply displays a full stop by default. To eliminate -this full stop (or replace it with something else, say a comma) you +this full stop (or replace it with something else, say, a comma) you will need to redefine \cs{glspostdescription} before the glossary is displayed. Alternatively, you can suppress it for a given entry by placing \ics{nopostdesc} in the entry's description. @@ -4161,7 +3686,7 @@ The styles described in this section are all defined in the package \isty{glossary-list}. Since they all use the \envname{description} environment, they are governed by the same parameters as that environment. These styles all ignore the entry's symbol. Note that -these styles will not be available if you use either the +these styles will automatically be available unless you use the \pkgopt{nolist} or \pkgopt{nostyles} package options. \begin{description} @@ -4231,8 +3756,14 @@ the same manner as \glostyle{listdotted}. The styles described in this section are all defined in the package \isty{glossary-long}. Since they all use the \envname{longtable} environment, they are governed by the same parameters as that -environment. Note that these styles will not be available if you -use either the \pkgopt{nolong} or \pkgopt{nostyles} package options. +environment. Note that these styles will automatically be available +unless you use the \pkgopt{nolong} or \pkgopt{nostyles} package +options. These styles fully justify the description and page list +columns. If you want ragged right formatting instead, use the +analogous styles described in +\ifmakedtx{\autoref{sec:longraggedstyles}}{\htmlref{Longtable Styles +(Ragged Right)}{sec:longraggedstyles}}. + \begin{description} \item[long] The \glostyle{long} style uses the \envname{longtable} @@ -4317,18 +3848,110 @@ descriptions and page lists. \end{description} \ifmakedtx{}{\toTop} +\subsubsection{Longtable Styles (Ragged Right)} +\label{sec:longraggedstyles} + +The styles described in this section are all defined in the package +\isty{glossary-longragged}. These styles are analogous to those +defined in \isty{glossary-long} but the multiline columns are left +justified instead of fully justified. Since these styles all use the +\envname{longtable} environment, they are governed by the same +parameters as that environment. The \isty{glossary-longragged} +package additionally requires the \isty{array} package. Note that +these styles will only be available if you explicitly load +\isty{glossary-longragged}: +\begin{verbatim} +\usepackage{glossaries} +\usepackage{glossary-longragged} +\end{verbatim} +Note that you can't set these styles using the \pkgopt{style} +package option since the styles aren't defined until after +the \sty{glossaries} package has been loaded. + +\begin{description} +\item[longragged] The \glostyle{longragged} style has two +columns: the first column contains the entry's name and the second +column contains the (left-justified) description followed by the +\term{number list}. The entry's symbol is ignored. +Sub groups are separated with a blank row. The width of the +first column is governed by the widest entry in that column. The +width of the second column is governed by the length +\ics{glsdescwidth}. Child entries have a similar format to the +parent entries except that their name is suppressed. + +\item[longraggedborder] The \glostyle{longraggedborder} style is like +\glostyle{longragged} but has horizontal and vertical lines around it. + +\item[longraggedheader] The \glostyle{longraggedheader} style is like +\glostyle{longragged} but has a header row. + +\item[longraggedheaderborder] The \glostyle{longraggedheaderborder} +style is like \glostyle{longraggedheader} but has horizontal and +vertical lines around it. + +\item[longragged3col] The \glostyle{longragged3col} style is like +\glostyle{longragged} but has three columns. The first column +contains the entry's name, the second column contains the (left +justified) description and the third column contains the (left +justified) \term{number list}. The entry's symbol is ignored. The +width of the first column is governed by the widest entry in that +column, the width of the second column is governed by the length +\ics{glsdescwidth}, and the width of the third column is governed by +the length \ics{glspagelistwidth}. + +\item[longragged3colborder] The \glostyle{longragged3colborder} +style is like the \glostyle{longragged3col} style but has horizontal +and vertical lines around it. + +\item[longragged3colheader] The \glostyle{longragged3colheader} style is like +\glostyle{longragged3col} but has a header row. + +\item[longragged3colheaderborder] The \glostyle{longragged3colheaderborder} style is +like \glostyle{longragged3colheader} but has horizontal and vertical lines +around it. + +\item[altlongragged4col] The \glostyle{altlongragged4col} style is +like \glostyle{longragged3col} but has an additional column in which +the entry's associated symbol appears. The width of the description +column is governed by the length \ics{glsdescwidth} and the width of +the page list column is governed by the length +\ics{glspagelistwidth}. The widths of the name and symbol columns +are governed by the widest entry in the given column. + +\item[altlongragged4colborder] The +\glostyle{altlongragged4colborder} style is like the +\glostyle{altlongragged4col} but has horizontal and vertical lines +around it. + +\item[altlongragged4colheader] The +\glostyle{altlongragged4colheader} style is like +\glostyle{altlongragged4col} but has a header row. + +\item[altlongragged4colheaderborder] The +\glostyle{altlongragged4colheaderborder} style is like +\glostyle{altlongragged4colheader} but has horizontal and vertical +lines around it. + +\end{description} +\ifmakedtx{}{\toTop} + \subsubsection{Supertabular Styles} \label{sec:superstyles} The styles described in this section are all defined in the package \isty{glossary-super}. Since they all use the \envname{supertabular} environment, they are governed by the same parameters as that -environment. Note that these styles will not be available if you -use either the \pkgopt{nosuper} or \pkgopt{nostyles} package options. -In general, the \envname{longtable} environment is better, but there -are some circumstances where it is better to use +environment. Note that these styles will automatically be available +unless you use the \pkgopt{nosuper} or \pkgopt{nostyles} package +options. In general, the \envname{longtable} environment is better, +but there are some circumstances where it is better to use \envname{supertabular}.\footnote{e.g.\ with the \isty{flowfram} -package.} +package.} These styles fully justify the description and page list +columns. If you want ragged right formatting instead, use the +analogous styles described in +\ifmakedtx{\autoref{sec:superraggedstyles}}{\htmlref{Supertabular +Styles (Ragged Right)}{sec:superraggedstyles}}. + \begin{description} \item[super] The \glostyle{super} style uses the \envname{supertabular} @@ -4414,15 +4037,105 @@ descriptions and page lists. \end{description} \ifmakedtx{}{\toTop} +\subsubsection{Supertabular Styles (Ragged Right)} +\label{sec:superraggedstyles} + +The styles described in this section are all defined in the package +\isty{glossary-superragged}. These styles are analogous to those +defined in \isty{glossary-super} but the multiline columns are left +justified instead of fully justified. Since these styles all use the +\envname{supertabular} environment, they are governed by the same +parameters as that environment. The \isty{glossary-superragged} +package additionally requires the \isty{array} package. Note that +these styles will only be available if you explicitly load +\isty{glossary-superragged}: +\begin{verbatim} +\usepackage{glossaries} +\usepackage{glossary-superragged} +\end{verbatim} +Note that you can't set these styles using the \pkgopt{style} +package option since the styles aren't defined until after +the \sty{glossaries} package has been loaded. + +\begin{description} +\item[superragged] The \glostyle{superragged} 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 (left +justified) description followed by the \term{number list}. The +entry's symbol is ignored. Sub groups are separated with a blank +row. The width of the first column is governed by the widest entry +in that column. The width of the second column is governed by the +length \ics{glsdescwidth}. Child entries have a similar format to +the parent entries except that their name is suppressed. + +\item[superraggedborder] The \glostyle{superraggedborder} style is +like \glostyle{superragged} but has horizontal and vertical lines +around it. + +\item[superraggedheader] The \glostyle{superraggedheader} style is +like \glostyle{superragged} but has a header row. + +\item[superraggedheaderborder] The +\glostyle{superraggedheaderborder} style is like +\glostyle{superraggedheader} but has horizontal and vertical lines +around it. + +\item[superragged3col] The \glostyle{superragged3col} style is like +\glostyle{superragged} but has three columns. The first column +contains the entry's name, the second column contains the (left +justified) description and the third column contains the (left +justified) \term{number list}. The entry's symbol is ignored. The +width of the first column is governed by the widest entry in that +column. The width of the second column is governed by the length +\ics{glsdescwidth}. The width of the third column is governed by the +length \ics{glspagelistwidth}. + +\item[superragged3colborder] The \glostyle{superragged3colborder} +style is like the \glostyle{superragged3col} style but has +horizontal and vertical lines around it. + +\item[superragged3colheader] The \glostyle{superragged3colheader} +style is like \glostyle{superragged3col} but has a header row. + +\item[superragged3colheaderborder] The +\glostyle{superragged3colheaderborder} style is like +\glostyle{superragged3colheader} but has horizontal and vertical +lines around it. + +\item[altsuperragged4col] The \glostyle{altsuperragged4col} style is +like \glostyle{superragged3col} but has an additional column in +which the entry's associated symbol appears. The column widths for +the name and symbol column are governed by the widest entry in the +given column. + +\item[altsuperragged4colborder] The +\glostyle{altsuperragged4colborder} style is like the +\glostyle{altsuperragged4col} style but has horizontal and vertical +lines around it. + +\item[altsuperragged4colheader] The +\glostyle{altsuperragged4colheader} style is like +\glostyle{altsuperragged4col} but has a header row. + +\item[altsuperragged4colheaderborder] The +\glostyle{altsuperragged4colheaderborder} style is like +\glostyle{altsuperragged4colheader} but has horizontal and vertical +lines around it. + +\end{description} +\ifmakedtx{}{\toTop} + \subsubsection{Tree-Like Styles} \label{sec:treestyles} The styles described in this section are all defined in the package \isty{glossary-tree}. These styles are designed for hierarchical glossaries but can also be used with glossaries that don't have -sub-entries. These styles will display the entry's symbol if it -exists. Note that these styles will not be available if you -use either the \pkgopt{notree} or \pkgopt{nostyles} package options. +sub-entries. These styles will display the entry's symbol if it +exists. Note that these styles will automatically be available +unless you use the \pkgopt{notree} or \pkgopt{nostyles} package +options. \begin{description} \item[index] The \glostyle{index} style is similar to the way @@ -4507,7 +4220,7 @@ 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}, +used in \cs{glossarystyle}). The second argument \meta{definitions} needs to redefine all of the following: \begin{description} @@ -4757,7 +4470,7 @@ than \cs{emph}.) Note however that \item \verb|\makefirstuc{{\'a}bc}| produces \MakeUppercase{\'a}bc -\item \verb|\makefirstuc{\ae bc}| produces \ifmakedtx{\MakeUppercase\ae bc}{\AE bc} +\item \verb|\makefirstuc{\ae bc}| produces \ifmakedtx{\MakeUppercase{\ae}bc}{\AE bc} \item \verb|\makefirstuc{{\ae}bc}| produces \ifmakedtx{\MakeUppercase{\ae}bc}{\AE bc} |