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