summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-09-25 00:48:57 +0000
committerKarl Berry <karl@freefriends.org>2009-09-25 00:48:57 +0000
commit1b5baf0f475cbfdc378718a46057c5c481b59065 (patch)
tree6ee2f82a5e33642af5af9bfffe47cbc0c48ecbfa /Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
parentf453f119c796c9607b391bbf26971fda1826c51c (diff)
glossaries update (24sep09)
git-svn-id: svn://tug.org/texlive/trunk@15452 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex167
1 files changed, 127 insertions, 40 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
index d17471374bd..8356d8f8b09 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex
@@ -19,6 +19,11 @@
\usepackage{creatdtx}
\ifmakedtx{
+\usepackage{dox}
+\doxitem{Option}{option}{package options}
+\doxitem{GlsKey}{key}{glossary keys}
+\doxitem{Style}{style}{glossary styles}
+
\renewcommand{\usage}[1]{\textit{\hyperpage{#1}}}
\renewcommand{\main}[1]{\hyperpage{#1}}
\newcommand{\see}[2]{\emph{see} #1}
@@ -27,7 +32,7 @@
\makeatother
\RecordChanges
\PageIndex
-\CheckSum{8711}
+\CheckSum{8767}
\CodelineNumbered
\newcommand*{\termdef}[1]{\emph{#1}\iterm{#1}}
\newcommand*{\term}[1]{#1\iterm{#1}}
@@ -62,8 +67,18 @@
\newcommand*{\Tableref}[1]{\htmlref{Table~}{#1}\ref{#1}}
\newenvironment{important}{}{}
\newcommand*{\tick}{X}
+
+\newcommand{\DescribeOption}[1]{}
+\newcommand{\DescribeGlsKey}[1]{}
+\newcommand{\DescribeStyle}[1]{}
}
+\makeatletter
+\renewenvironment{theindex}{\twocolumn[\index@prologue]
+\let\item\@idxitem
+\ignorespaces
+}{}
+\makeatother
\newcommand*{\ifirstuse}{\iterm{first use}}
\newcommand*{\firstuse}{first use\ifirstuse}
@@ -82,14 +97,14 @@
\newcommand*{\pkgoptni}[1]{\textsf{#1}}
\newcommand*{\ipkgopt}[2][]{%
\ifthenelse{\equal{#1}{}}{%
-\index{package options>#2=\pkgoptni{#2}|hyperpage}}{%
-\index{package options>#2=\pkgoptni{#2}>#1=\pkgoptni{#1}|hyperpage}}}
+\index{package options:>#2={\protect\ttfamily #2}|main}}{%
+\index{package options:>#2={\protect\ttfamily #2}>#1={\protect\ttfamily #1}|main}}}
\newcommand*{\pkgopt}[2][]{%
\ifthenelse{\equal{#1}{}}{%
-\pkgoptni{#2}\index{package options>#2=\pkgoptni{#2}|hyperpage}}{%
-\pkgoptni{#2=#1}\index{package options>#2=\pkgoptni{#2}>#1=\pkgoptni{#1}|hyperpage}}}
-\newcommand*{\pkgoptval}[2]{\pkgoptni{#1}\index{package options>#2=\pkgoptni{#2}>#1=\pkgoptni{#1}|hyperpage}}
-\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles>#1|hyperpage}}
+\pkgoptni{#2}\index{package options:>#2={\protect\ttfamily #2}|main}}{%
+\pkgoptni{#2=#1}\index{package options:>#2={\protect\ttfamily #2}>#1={\protect\ttfamily #1}|main}}}
+\newcommand*{\pkgoptval}[2]{\pkgoptni{#1}\index{package options:>#2={\protect\ttfamily #2}>#1={\protect\ttfamily#1}|main}}
+\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\ttfamily#1}|main}}
\newcommand*{\filetype}[1]{\texttt{#1}\index{file types>#1|hyperpage}}
\newcommand*{\sty}[1]{\textsf{#1}}
\newcommand*{\isty}[1]{\sty{#1}\index{#1 package=\sty{#1} package|hyperpage}}
@@ -131,7 +146,7 @@
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{glossaries.sty v 2.02: \LaTeXe\ Package to Assist Generating Glossaries}
+ \title{glossaries.sty v 2.03: \LaTeXe\ Package to Assist Generating Glossaries}
\author{Nicola L.C. Talbot\\[10pt]
School of Computing Sciences\\
University of East Anglia\\
@@ -139,7 +154,7 @@ Norwich. Norfolk\\
NR4 7TJ. United Kingdom.\\
\url{http://theoval.cmp.uea.ac.uk/~nlct/}}
- \date{13th July 2009}
+ \date{23rd September 2009}
\maketitle
\tableofcontents
@@ -260,7 +275,7 @@ The sample documents are as follows:
You can test your installation using this file. To create the
complete document you will need to do the following steps:
\begin{enumerate}
- \item Run \texttt{minimalgls.tex} through \LaTeX\ by either
+ \item Run \texttt{minimalgls.tex} through \LaTeX\ either by
typing
\begin{verbatim}
latex minimalgls
@@ -278,7 +293,7 @@ latex minimalgls
package.
\item Run \appname{makeglossaries} on the document. This can
- be done on a terminal by either typing
+ be done on a terminal either by typing
\begin{verbatim}
makeglossaries minimalgls
\end{verbatim}
@@ -489,7 +504,7 @@ you don't need to supply any additional information. If you
don't use \appname{makeglossaries}, you will need to specify the
required information. Note that if you set the style file to
\texttt{samplexdy-mc.xdy} you must also specify \ics{noist},
-otherwise the \isty{glossaries} package will overwrite
+otherwise the \sty{glossaries} package will overwrite
\texttt{samplexdy-mc.xdy} and you will lose the \dq{Mc} letter group.
To create the document do:
@@ -604,8 +619,8 @@ me the relevant translations either via email or via
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, however,
-it may not pick up on the required languages, so if the predefined
+\isty{translator} package will be loaded automatically. However,
+it may not pick up on the required languages so, if the predefined
text is not translated, you may need to explicitly load the
\isty{translator} package with the required languages. For example:
\begin{verbatim}
@@ -633,7 +648,7 @@ to provide the translations. For example:
\end{verbatim}
The following languages are currently supported by the
-\isty{glossaries} package:
+\sty{glossaries} package:
\begin{center}
\begin{tabular}{lc}
\bfseries Language & \bfseries As from version\\
@@ -690,14 +705,38 @@ 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 you
+can change the translations using \cs{deftranslation}. See the
+\isty{translator} documentation for further details.
-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:
+If you don't want to use the \isty{translator} interface, you
+can suppress it using the package option \pkgopt[false]{translate},
+and either load \isty{glossaries-babel} after \sty{glossaries}
+or specify you're own translations. For example:
\begin{verbatim}
-\deftranslation[to=Irish]{Symbol (glossaries)}{Siombail}
+\documentclass[british]{article}
+
+\usepackage{babel}
+\usepackage[translate=false]{glossaries}
+\usepackage{glossaries-babel}
+\end{verbatim}
+or:
+\begin{verbatim}
+\documentclass[british]{article}
+
+\usepackage{babel}
+\usepackage[translate=false]{glossaries}
+
+\addto\captionsbritish{%
+ \renewcommand*{\glossaryname}{List of Terms}%
+ \renewcommand*{\acronymname}{List of Acronyms}%
+ \renewcommand*{\entryname}{Notation}%
+ \renewcommand*{\descriptionname}{Description}%
+ \renewcommand*{\symbolname}{Symbol}%
+ \renewcommand*{\pagelistname}{Page List}%
+ \renewcommand*{\glssymbolsgroupname}{Symbols}%
+ \renewcommand*{\glsnumbersgroupname}{Numbers}%
+}
\end{verbatim}
Note that \appname{xindy} provides much better multi-lingual
@@ -848,6 +887,11 @@ perl makeglossaries myDoc
There is a batch file called \texttt{makeglossaries.bat} which
does this for Windows users, but you must have Perl installed to
be able to use it.
+
+The \appname{makeglossaries} script contains POD (Plain Old
+Documentation). If you want, you can create a man page for
+\appname{makeglossaries} using \appname{pod2man} and move the
+resulting file onto the man path.
\ifmakedtx{}{\toTop}
\subsubsection{Using xindy explicitly}
@@ -1046,6 +1090,13 @@ the acronyms. This command converts lower case letters to small
capitals, while upper case letters remain their usual size. Therefore
you need to specify the acronym in lower case letters.
+\item \textbf{Q.} My acronyms won't break across a line when they're
+expanded.
+
+\textbf{A.} PDF\LaTeX\ can break hyperlinks across a line, but
+\LaTeX\ can't. If you can't use PDF\LaTeX\ then disable the first use
+links using the package option \pkgopt[false]{hyperfirst}.
+
\item \textbf{Q.} How do I change the font that the acronyms are displayed in?
\textbf{A.} The easiest way to do this is to specify the \pkgopt{smaller} package
@@ -1181,6 +1232,17 @@ site.
The \sty{glossaries} package options are as follows:
\begin{description}
+\item[\pkgopt{nowarn}] This suppresses all warnings generated by
+the \sty{glossaries} package.
+
+\item[\pkgopt{nomain}] This suppresses the creation of the main
+glossary. Note that if you use this option, you must create another
+glossary in which to put all your entries (either via the
+\pkgopt{acronym} package option described below or via
+\ics{newglossary} described in
+\ifmakedtx{\autoref{sec:newglossary}}{\htmlref{Defining New
+Glossaries}{sec:newglossary}}).
+
\item[\pkgopt{toc}] Add the glossaries to the table of contents.
Note that an extra \LaTeX\ run is required with this option.
@@ -1207,15 +1269,6 @@ 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,
@@ -1235,9 +1288,10 @@ is equivalent to
\end{verbatim}
You can change this value later in the document using\\[10pt]
\DescribeMacro{\setglossarysection}\cs{setglossarysection}\marg{name}\\[10pt]
-where \meta{name} is the sectional unit. The start of each glossary
-adds information to the page header via
-\DescribeMacro{glossarymark}\cs{glossarymark}\marg{glossary title}.
+where \meta{name} is the sectional unit.
+
+The start of each glossary adds information to the page header via
+\DescribeMacro{\glossarymark}\cs{glossarymark}\marg{glossary title}.
This defaults to \cs{@mkboth}, but you may need to redefine it.
For example, to only change the right header:
\begin{verbatim}
@@ -1402,7 +1456,11 @@ for further details.
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}}
+\ics{newacronym} and the way that acronyms are displayed.
+If you use this option, you will need to include the \isty{relsize}
+package or otherwise define \ics{textsmaller} or redefine
+\ics{acronymfont}. See
+\ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}}
for further details.
\item[\pkgopt{dua}] This option changes the definition of
@@ -1451,8 +1509,30 @@ 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.
+\item[\pkgopt{translate}] This is a boolean option. The default is
+\pkgoptval{true}{translate} if \isty{babel} or \isty{translator}
+have been loaded, otherwise the default value is
+\pkgoptval{false}{translate}.
+
+ \begin{description}
+ \item[{\pkgopt[true]{translate}}] If the \isty{translator} package
+ is installed, it will be loaded and the translations will be
+ provided by the \isty{translator} package interface. If the
+ \isty{translator} package isn't installed, the
+ \isty{glossaries-babel} package will be loaded and the translations
+ will be provided using \sty{babel}'s
+ \cs{addto}\cs{caption}\meta{language} mechanism.
+
+ \item[{\pkgopt[false]{translate}}] Don't provide translations, even
+ if \isty{babel} has been loaded. You can then provide you're
+ own translations or explicitly load \isty{glossaries-babel}.
+ \end{description}
+
+\item[\pkgopt{hyperfirst}] This is a boolean option that specifies
+whether each term has a hyperlink on \firstuse. The default is
+\pkgopt[true]{hyperfirst} (terms on first use have a hyperlink,
+unless explicitly suppressed using starred versions of commands
+such as \cs{gls*}).
\end{description}\ifmakedtx{}{\toTop}
@@ -2414,7 +2494,13 @@ 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).\ifmakedtx{}{\toTop}
+defined (for example, by the \isty{hyperref} package).
+
+You can disable just the first use links using the package
+option \pkgopt[false]{hyperfirst}. Note that this option only
+affects commands that recognise the \firstuse\ flag, for example
+\ics{gls}, \ics{glspl} and \ics{glsdisp} but not \ics{glslink}.
+\ifmakedtx{}{\toTop}
\subsection{Adding an Entry to the Glossary Without Generating Text}
\label{sec:glsadd}
@@ -2638,7 +2724,8 @@ defined).
\item[{\gloskey[printglossary]{toctitle}}] This is the title
to use for the table of contents (if the \pkgopt{toc} package
-option has been used). If omitted, the glossary title is used.
+option has been used). It may also be used for the page header,
+depending on the page style. If omitted, the glossary title is used.
\item[{\gloskey[printglossary]{style}}] This specifies which
glossary style to use for this glossary, overriding the effect
@@ -3473,7 +3560,7 @@ replacement \sty{glossaries} package. In addition, the old
\cs{}\meta{acr-name} when defining the acronym \meta{acr-name}.
In order to facilitate migrating from the old package to the new
-one, the \isty{glossaries} package\footnote{as from version 1.18}
+one, the \sty{glossaries} package\footnote{as from version 1.18}
provides the command:\\[10pt]
\DescribeMacro{\oldacronym}\cs{oldacronym}\oarg{label}\marg{abbrv}\marg{long}\marg{key-val list}\\[10pt]
This uses the same syntax as the \isty{glossary} package's
@@ -3497,7 +3584,7 @@ names consisting of alphabetical characters. This is also true for
\isty{xspace} package.
\end{important}
-The \isty{glossaries} package doesn't load the \isty{xspace} package
+The \sty{glossaries} package doesn't load the \isty{xspace} package
since there are both advantages and disadvantages to using
\ics{xspace} in \cs{}\meta{label}. If you don't use the
\isty{xspace} package you need to explicitly force a space using