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 | 229 |
1 files changed, 204 insertions, 25 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex index ac8cf241478..52a7a33f3c1 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex @@ -23,7 +23,7 @@ \makeatother \RecordChanges \PageIndex -\CheckSum{5121} +\CheckSum{5329} \CodelineNumbered \newcommand*{\termdef}[1]{\emph{#1}\iterm{#1}} \newcommand*{\term}[1]{#1\iterm{#1}} @@ -109,7 +109,7 @@ \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{glossaries.sty v 1.14: \LaTeXe\ Package to Assist Generating Glossaries} + \title{glossaries.sty v 1.16: \LaTeXe\ Package to Assist Generating Glossaries} \author{Nicola L.C. Talbot\\[10pt] School of Computing Sciences\\ University of East Anglia\\ @@ -117,7 +117,7 @@ Norwich. Norfolk\\ NR4 7TJ. United Kingdom.\\ \url{http://theoval.cmp.uea.ac.uk/~nlct/}} - \date{18th June 2008} + \date{27th August 2008} \maketitle \tableofcontents @@ -243,7 +243,7 @@ in your document preamble: \deftranslation[to=Irish]{Symbol (glossaries)}{Siombail} \end{verbatim} -\subsection{Generating the associated glossary files} +\subsection{Generating the Associated Glossary Files} \label{sec:makeglossaries} The \sty{glossaries} package comes with the Perl script @@ -659,14 +659,14 @@ The primary definition of \glspl[format=textbf]{singmtx}. \end{verbatim} In this example the relevant glossary entry will have the page number in bold (since it uses \cs{textbf}) but -it will no longer have a hyperlink (if hyperlinks are enabled.) +it will no longer have a hyperlink (if hyperlinks are enabled). \item The \sty{glossaries} package provides commands to change the font whilst ensuring that the number remains a hyperlink. These are of the form \cs{hyper}\meta{xx} and are equivalent to the standard font changing commands of the form \cs{text}\meta{xx}, as well as \ics{hyperemph} -(which uses \ics{emph}.) For example: +(which uses \ics{emph}). For example: \begin{verbatim} The primary definition of \glspl[format=hyperbf]{singmtx}. \end{verbatim} @@ -717,11 +717,21 @@ document will be placed in the glossary. If you have defined a term that doesn't appear in the document, then it means you haven't used it in the text (either via \ics{glslink} or \ics{gls} and related commands, or via \ics{glsadd} -or \ics{glsaddall}.) +or \ics{glsaddall}). \item 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} @@ -749,8 +759,12 @@ symbol={m}} The predefined glossary styles that display the entry symbol are: \glostyle{long4col}, \glostyle{long4colheader}, \glostyle{long4colborder}, \glostyle{long4colheaderborder}, + \glostyle{altlong4col}, \glostyle{altlong4colheader}, +\glostyle{altlong4colborder}, \glostyle{altlong4colheaderborder}, \glostyle{super4col}, \glostyle{super4colheader}, -\glostyle{super4colborder} and \glostyle{super4colheaderborder}. +\glostyle{super4colborder}, \glostyle{super4colheaderborder}. +\glostyle{altsuper4col}, \glostyle{altsuper4colheader}, +\glostyle{altsuper4colborder} and \glostyle{altsuper4colheaderborder}. All the other styles supplied by this package ignore the associated symbol. @@ -886,7 +900,7 @@ glossary styles are listed \ifmakedtx{in \autoref{sec:styles}}{\htmlref{later}{s \item[\pkgopt{nonumberlist}] This option will suppress the associated number lists\iterm{number list} in the glossaries (see also -\ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}.) +\ifmakedtx{\autoref{sec:numberlists}}{\htmlref{Number Lists}{sec:numberlists}}). \item[\pkgopt{counter}] This is a \meta{key}=\meta{value} option. The value should be the name of the default counter to use in the number @@ -1128,7 +1142,7 @@ name={Perl}, description={A scripting language}} \newglossaryentry{tex}{name={\TeX}, -description={A typesetting language}} +description={A typesetting language},sort={TeX}} \newglossaryentry{html}{type=\glsdefaulttype, name={html}, @@ -1196,7 +1210,22 @@ Once you have defined a glossary entry using document using one of the commands listed in this section. The text which appears at that point in the document when using one of these commands is referred to as the -\termdef{link text} (even if there are no hyperlinks). +\termdef{link text} (even if there are no hyperlinks). The commands +in this section also add a line to an external file that is used +by \appname{makeindex} to generate the relevant entry in the +glossary. It is strongly recommended that you don't use the commands +defined in this section in the arguments of sectioning or caption +commands. This is particularly important if you are using the +\sty{glossaries} package in conjunction with the \isty{hyperref} package. +Instead, use one of the commands listed in +\ifmakedtx{\autoref{sec:glsnolink}}{\htmlref{Using Glossary Terms +Without Links}{sec:glsnolink}} (such as \cs{glsentrytext}) or provide an alternative via +the optional argument to the sectioning/caption command. +Examples: +\begin{verbatim} +\section{An overview of \glsentrytext{perl}} +\section[An overview of Perl]{An overview of \gls{perl}} +\end{verbatim} The way the \term{link text} is displayed depends on \DescribeMacro{\glstextformat}\cs{glstextformat}\marg{text}. @@ -1495,7 +1524,15 @@ supplied in the final optional argument to \cs{gls} or \cs{glspl} (or their uppercase variants). The default definitions of \cs{glsdisplay} and \cs{glsdisplayfirst} simply print the first argument immediately followed by the fourth argument. -The remaining arguments are ignored. +The remaining arguments are ignored. Note that \ics{glslink} (which +is used by commands like \cs{gls} and \cs{glspl}) sets +\DescribeMacro{\glslabel}\ics{glslabel} to the label for the given +entry (i.e.\ the label supplied to the mandatory argument to +\cs{gls}), so it is possible to use this label in the definition of +\cs{glsdisplay} or \cs{glsdisplayfirst} to supply additional +information using any of the commands described in +\ifmakedtx{\autoref{sec:glsnolink}}{\htmlref{Using Glossary Terms +Without Links}{sec:glsnolink}}, if required. For example, suppose you want a glossary of measurements and units, you can use the \gloskey{symbol} key to store the unit: @@ -1582,9 +1619,9 @@ and\\[10pt] respectively. The effect can be localised by placing the commands within a group. Note that you should only use \cs{glsenablehyper} if the commands \ics{hyperlink} and \ics{hypertarget} have been -defined (for example, by the \isty{hyperref} package). +defined (for example, by the \isty{hyperref} package).\ifmakedtx{}{\toTop} -\subsection{Adding an entry to the glossary without generating text} +\subsection{Adding an Entry to the Glossary Without Generating Text} \label{sec:glsadd} \DescribeMacro{\glsadd} @@ -1619,6 +1656,72 @@ do: \end{verbatim} \ifmakedtx{}{\toTop} +\subsection{Using Glossary Terms Without Links} +\label{sec:glsnolink} + +The commands described in this section display entry details without +adding any information to the glossary. They don't use +\cs{glstextformat}, they don't have any optional arguments, +they don't affect the flag that determines if the term has been +used and they don't produce hyperlinks. +\par\vskip10pt\noindent +\DescribeMacro{\glsentryname}\cs{glsentryname}\marg{label}\\ +\DescribeMacro{\Glsentryname}\cs{Glsentryname}\marg{label}\par\vskip10pt\noindent +These commands display the name of the glossary entry given by +\meta{label}, as specified by the \gloskey{name} key. +\cs{Glsentryname} makes the first letter uppercase. +\par\vskip10pt\noindent +\DescribeMacro{\glsentrytext}\cs{glsentrytext}\marg{label}\\ +\DescribeMacro{\Glsentrytext}\cs{Glsentrytext}\marg{label}\par\vskip10pt\noindent +These commands display the subsequent use text for the glossary entry +given by \meta{label}, as specified by the \gloskey{text} key. +\cs{Glsentrytext} makes the first letter uppercase. +\par\vskip10pt\noindent +\DescribeMacro{\glsentryplural}\cs{glsentryplural}\marg{label}\\ +\DescribeMacro{\Glsentryplural}\cs{Glsentryplural}\marg{label}\par\vskip10pt\noindent +These commands display the subsequent use plural text for the glossary +entry given by \meta{label}, as specified by the \gloskey{plural} key. +\cs{Glsentryplural} makes the first letter uppercase. +\par\vskip10pt\noindent +\DescribeMacro{\glsentryfirst}\cs{glsentryfirst}\marg{label}\\ +\DescribeMacro{\Glsentryfirst}\cs{Glsentryfirst}\marg{label}\par\vskip10pt\noindent +These commands display the first use text for the glossary entry +given by \meta{label}, as specified by the \gloskey{first} key. +\cs{Glsentryfirst} makes the first letter uppercase. +\par\vskip10pt\noindent +\DescribeMacro{\glsentryfirstplural}\cs{glsentryfirstplural}\marg{label}\\ +\DescribeMacro{\Glsentryfirstplural}\cs{Glsentryfirstplural}\marg{label}\par\vskip10pt\noindent +These commands display the plural form of the first use text for the +glossary entry given by \meta{label}, as specified by the +\gloskey{firstplural} key. \cs{Glsentryfirstplural} makes the first +letter uppercase. +\par\vskip10pt\noindent +\DescribeMacro{\glsentrydesc}\cs{glsentrydesc}\marg{label}\\ +\DescribeMacro{\Glsentrydesc}\cs{Glsentrydesc}\marg{label}\par\vskip10pt\noindent +These commands display the description for the glossary entry given by +\meta{label}. \cs{Glsentrydesc} makes the first letter uppercase. +\par\vskip10pt\noindent +\DescribeMacro{\glsentrydescplural}\cs{glsentrydescplural}\marg{label}\\ +\DescribeMacro{\Glsentrydescplural}\cs{Glsentrydescplural}\marg{label}\par\vskip10pt\noindent +These commands display the plural description for the glossary entry +given by \meta{label}. \cs{Glsentrydescplural} makes the first letter +uppercase. +\par\vskip10pt\noindent +\DescribeMacro{\glsentrysymbol}\cs{glsentrysymbol}\marg{label}\\ +\DescribeMacro{\Glsentrysymbol}\cs{Glsentrysymbol}\marg{label}\par\vskip10pt\noindent +These commands display the symbol for the glossary entry given by +\meta{label}. \cs{Glsentrysymbol} makes the first letter uppercase. +\par\vskip10pt\noindent +\DescribeMacro{\glsentrysymbolplural}\cs{glsentrysymbolplural}\marg{label}\\ +\DescribeMacro{\Glsentrysymbolplural}\cs{Glsentrysymbolplural}\marg{label}\par\vskip10pt\noindent +These commands display the plural symbol for the glossary entry given by +\meta{label}. \cs{Glsentrysymbolplural} makes the first letter uppercase. + +For further information see \ifmakedtx{\autoref{sec:code:glsnolink}}{the +section \dq{Displaying entry details without adding information to +the glossary} in the document \texttt{glossaries.pdf}}. +\ifmakedtx{}{\toTop} + \subsection{Displaying a glossary} \DescribeMacro{\printglossaries} @@ -1756,7 +1859,8 @@ not sure whether the \pkgopt{acronym} option has been used, you can identify the list of acronyms by the command \DescribeMacro{\acronymtype}\cs{acronymtype} which is set to \texttt{acronym}, if the \pkgopt{acronym} option has been used, -otherwise it is set to \texttt{main}.\ifmakedtx{}{\toTop} +otherwise it is set to \texttt{main}. +\ifmakedtx{}{\toTop} \subsection{Acronyms} \label{sec:acronyms} @@ -1936,7 +2040,11 @@ Each of the package options \pkgopt{smallcaps}, \pkgopt{smaller}, and \pkgopt{description} use \ics{defglsdisplay} and \ics{defglsdisplayfirst} (described \ifmakedtx{in \autoref{sec:glsdisplay}}{\htmlref{earlier}{sec:glsdisplay}}) -to change the way the link text is displayed. +to change the way the link text is displayed. This means that these +package options only work for the glossary type given by +\cs{acronymtype}. If you have multiple lists of acronyms, you +will need to make the appropriate changes for each additional +glossary type. \begin{description} \item[\pkgopt{description},\pkgopt{footnote}]\ifmakedtx{\mbox{}\par}{} @@ -2109,7 +2217,7 @@ produce all upper case text. \ifmakedtx{}{\toTop} -\subsection{Unsetting and resetting entry flags} +\subsection{Unsetting and Resetting Entry Flags} When using \ics{gls}, \ics{glspl} and their uppercase variants it is possible that you may want to use the value given by the @@ -2187,7 +2295,10 @@ 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. +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}. \item[longborder] The \glostyle{longborder} style is like \glostyle{long} but has horizontal and vertical lines around it. @@ -2202,7 +2313,11 @@ around it. \item[long3col] The \glostyle{long3col} style is like \glostyle{long} but has three columns. The first column contains the entry's name, the second column contains the description -and the third column contains the \term{number list}. +and the third column contains the \term{number list}. 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[long3colborder] The \glostyle{long3colborder} style is like the \glostyle{long3col} style but has horizontal and vertical @@ -2217,7 +2332,10 @@ around it. \item[long4col] The \glostyle{long4col} style is like \glostyle{long3col} but has an additional column in which the -entry's associated symbol appears. +entry's associated symbol appears. This style is used for brief +single line descriptions. The column widths are governed by the +widest entry in the given column. Use \glostyle{altlong4col} for long +descriptions. \item[long4colborder] The \glostyle{long4colborder} style is like the \glostyle{long4col} style but has horizontal and vertical @@ -2230,11 +2348,34 @@ lines around it. like \glostyle{long4colheader} but has horizontal and vertical lines around it. +\item[altlong4col] The \glostyle{altlong4col} style is like +\glostyle{long4col} but allows multi-line descriptions and page lists. +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 width of the name +and symbol columns is governed by the widest entry in the +given column. + +\item[altlong4colborder] The \glostyle{altlong4colborder} style is like +the \glostyle{long4colborder} but allows multi-line descriptions and +page lists. + +\item[altlong4colheader] The \glostyle{altlong4colheader} style is like +\glostyle{long4colheader} but allows multi-line descriptions and +page lists. + +\item[altlong4colheaderborder] The \glostyle{altlong4colheaderborder} +style is like \glostyle{long4colheaderborder} but allows multi-line +descriptions and page lists. + \item[super] The \glostyle{super} style uses the \envname{supertabular} environment (defined by the \isty{supertabular} package). It has two columns: the first column contains the entry's name and the second column contains the description followed by the \term{number list}. -Sub groups are separated with a blank row. +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}. \item[superborder] The \glostyle{superborder} style is like \glostyle{super} but has horizontal and vertical lines around it. @@ -2249,7 +2390,11 @@ around it. \item[super3col] The \glostyle{super3col} style is like \glostyle{super} but has three columns. The first column contains the entry's name, the second column contains the description -and the third column contains the \iterm{number list}. +and the third column contains the \iterm{number list}. 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[super3colborder] The \glostyle{super3colborder} style is like the \glostyle{super3col} style but has horizontal and vertical @@ -2264,7 +2409,10 @@ lines around it. \item[super4col] The \glostyle{super4col} style is like \glostyle{super3col} but has an additional column in which the -entry's associated symbol appears. +entry's associated symbol appears. This style is designed for +entries with brief single line descriptions. The column widths are governed by the +widest entry in the given column. Use \glostyle{altsuper4col} +for longer descriptions. \item[super4colborder] The \glostyle{super4colborder} style is like the \glostyle{super4col} style but has horizontal and vertical @@ -2277,12 +2425,43 @@ lines around it. is like \glostyle{super4colheader} but has horizontal and vertical lines around it. +\item[altsuper4col] The \glostyle{altsuper4col} style is like +\glostyle{super4col} but allows multi-line descriptions and page +lists. +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 width of the name +and symbol columns is governed by the widest entry in the +given column. + +\item[altsuper4colborder] The \glostyle{altsuper4colborder} style is like +the \glostyle{super4colborder} style but allows multi-line descriptions +and page lists. + +\item[altsuper4colheader] The \glostyle{altsuper4colheader} style is like +\glostyle{super4colheader} but allows multi-line descriptions and +page lists. + +\item[altsuper4colheaderborder] The \glostyle{altsuper4colheaderborder} +style is like \glostyle{super4colheaderborder} but allows multi-line +descriptions and page lists. + \end{description} The glossary style can be set using the \pkgopt{style} package option or using the \gloskey[printglossary]{style} key in the optional argument to \ics{printglossary} or using the command:\\[10pt] \DescribeMacro{\glossarystyle}\cs{glossarystyle}\marg{style-name}\\[10pt] +The tabular-like styles that allow multi-line descriptions and page +lists use the length \DescribeMacro{\glsdescwidth}\cs{glsdescwidth} to +set the width of the description column and the length +\DescribeMacro{\glspagelistwidth}\cs{glspagelistwidth} to set the +width of the page list column. These will need to be changed using +\cs{setlength} if the glossary is too wide. Note that the +\glostyle{long4col} and \glostyle{super4col} styles (and their header and border +variations) don't use these lengths as they are designed for single +line entries. Instead you should use the analogous +\glostyle{altlong4col} and \glostyle{altsuper4col} styles. Note that if you use the \gloskey[printglossary]{style} key in the optional argument to \ics{printglossary}, it will override any @@ -2301,7 +2480,7 @@ override any previous style definitions, so, again: \glossarystyle{long} \end{verbatim} will reset \cs{glsgroupskip} back to its default definition for the -named glossary style (\dq{long} in this case). If you want to +named glossary style (\glostyle{long} in this case). If you want to modify the styles, either use \ics{newglossarystyle} (described in the next section) or make the modifications after \ics{glossarystyle}. @@ -2331,7 +2510,7 @@ needs to redefine all of the following: This environment defines how the main body of the glossary should be typeset. Note that this does not include the section heading, the glossary preamble (defined by \cs{glossarypreamble}) or the -glossary postamble (defined by \cs{glossarypostamble}.) For example, +glossary postamble (defined by \cs{glossarypostamble}). For example, the \glostyle{list} style uses the \envname{description} environment, so the \envname{theglossary} environment is simply redefined to begin and end the \envname{description} environment. |