summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-06-14 22:31:40 +0000
committerKarl Berry <karl@freefriends.org>2010-06-14 22:31:40 +0000
commitb3f1741ccbe6dede2fc5cc309815e40728c0330f (patch)
treee9c7d2ffc516d8fff6defbf3b85205078e1701f9 /Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
parentfa2a29ef6564da92ff9b4caede3dd5456dd48eb6 (diff)
glossaries 2.06 (14jun10)
git-svn-id: svn://tug.org/texlive/trunk@18975 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex188
1 files changed, 86 insertions, 102 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex b/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
index 32affd8783e..6c2899afc2f 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
@@ -1,82 +1,57 @@
-\documentclass[a4paper,12pt]{article}
+\documentclass{nlctdoc}
-\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
-\usepackage{cmap}
+\ifpdf
+\usepackage[T1]{fontenc}
\usepackage{mathpazo}
\usepackage[scaled=.86]{helvet}
\usepackage{courier}
\usepackage{xr-hyper}
+\fi
\usepackage[colorlinks,pdfauthor={Nicola L.C. Talbot},
pdftitle={The glossaries package: a guide for beginners}]{hyperref}
-\usepackage{html}
\title{The glossaries package: a guide for beginners}
\author{Nicola L.C. Talbot}
-\date{24th September 2009}
-
-%\begin{latexonly}
-\newcommand*{\sty}[1]{\textsf{#1}}
-\newcommand*{\env}[1]{\textsf{#1}}
-\newcommand*{\pkgopt}[1]{\textsf{#1}}
-\newcommand*{\dq}[1]{``#1''}
-\newcommand*{\gloskey}[1]{\textsf{#1}}
-
-\newcommand*{\meta}[1]{\textnormal{$\langle$\emph{#1}$\rangle$}}
-\newenvironment{definition}{\par\vskip\baselineskip\noindent
-\ignorespaces}{\par\vskip\baselineskip\noindent\ignorespacesafterend}
-%\end{latexonly}
-\begin{htmlonly}
-\newcommand{\sty}[1]{\texttt{#1}}
-\newcommand{\env}[1]{\texttt{#1}}
-\renewcommand{\LaTeX}{LaTeX}
-\renewcommand{\TeX}{TeX}
-\newcommand*{\pkgopt}[1]{\texttt{#1}}
-\newcommand*{\dq}[1]{"#1"}
-\newcommand*{\gloskey}[1]{\texttt{#1}}
-\newcommand*{\meta}[1]{\textnormal{\textless\emph{#1}\textgreater}}
-\newenvironment{definition}{\par}{\par}
-\end{htmlonly}
-
-\newcommand*{\marg}[1]{\texttt{\char`\{\meta{#1}\char`\}}}
-\newcommand*{\oarg}[1]{\texttt{[\meta{#1}]}}
-\newcommand*{\cs}[1]{\texttt{\char`\\#1}}
-\newcommand*{\app}[1]{\texttt{#1}}
-
-\externaldocument{glossaries}
+\date{2010-05-28}
+
+\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}}
+\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}}
+
+\ifpdf\externaldocument{glossaries}\fi
\begin{document}
\maketitle
-\tableofcontents
\begin{abstract}
-This document is a brief guide to the \sty{glossaries} package for
+This document is a brief guide to the \styfmt{glossaries} package for
beginners who find the size of the main user manual daunting and, as
such, it only covers the basics. For more advanced topics, see the
-\latexhtml{main user manual (\href{glossaries.pdf}{glossaries.pdf})}{\htmladdnormallink{main user manual}{glossaries-manual.html}}.
+\altdocref{main user manual}{glossaries}{glossaries-manual}.
\end{abstract}
+\tableofcontents
+
\section{What Do I Need?}
\label{requirements}
-You need to have the \sty{glossaries} package installed. You also
+You need to have the \styfmt{glossaries} package installed. You also
need to have the following packages installed: \sty{ifthen},
\sty{xkeyval} (at least version 2.5f), \sty{xfor} and \sty{amsgen}.
You may also need \sty{longtable}, \sty{supertabular} and
-\sty{array}, depending on what glossary style you want to use.
-All these packages can be downloaded from CTAN if you don't have
-them installed. See \htmladdnormallink{Installing things on a
-(La)TeX System}{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=installthings}\latex{\footnote{\url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=installthings}}}
-for further assistance.
-
-You also need an indexing application. The \sty{glossaries} package
-is configured to use either \app{makeindex} or \app{xindy}.
+\sty{array}, depending on what glossary style you want to use. All
+these packages can be downloaded from CTAN if you don't have them
+installed. See
+\urlfootref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=installthings}{\qt{Installing
+things on a (La)TeX System}} for further assistance.
+
+In addition, you need an indexing application. The \sty{glossaries}
+package is configured to use either \app{makeindex} or \app{xindy}.
\app{Makeindex} should be available on all \TeX\ systems. It's
possible you may not have \app{xindy} installed, but it can be
-downloaded from the \htmladdnormallink{xindy home
-page}{http://www.xindy.org/}.\latex{\footnote{\url{http://www.xindy.org/}}}
-The \sty{glossaries} package provides a helper Perl script called
-\app{makeglossaries} which will act as an interface to
+downloaded from the \urlfootref{http://www.xindy.org/}{xindy home
+page}. The \sty{glossaries} package provides a helper Perl script
+called \app{makeglossaries} which will act as an interface to
\app{makeindex} or \app{xindy}. If you want to use
\app{makeglossaries}, you need to have Perl installed, but you can
use \app{makeindex} or \app{xindy} directly if you prefer.
@@ -89,7 +64,7 @@ The most obvious things to do is to remember to load the
\begin{verbatim}
\usepackage{glossaries}
\end{verbatim}
-Note that the \sty{glossaries} package must be loaded \emph{after}
+Note that the \styfmt{glossaries} package must be loaded \emph{after}
the \sty{hyperref} package (contrary to the general advice that
\sty{hyperref} should be loaded last). The \sty{glossaries} package
should also be loaded after \sty{html}, \sty{inputenc},
@@ -101,12 +76,13 @@ glossaries, you need to specify this in the package options:
\usepackage[xindy]{glossaries}
\end{verbatim}
Other package options are described in
-\latexhtml{section~\ref{sec:pkgopts}}{the section
-\htmladdnormallink{\dq{Package Options}}{glossaries-manual.html#sec:pkgopts}} in the main \sty{glossaries} user manual.
+%\latexhtml{section~\ref{sec:pkgopts}}{the section
+%\htmladdnormallink{\qt{Package Options}}{glossaries-manual.html#sec:pkgopts}}
+\xrsectionref{sec:pkgopts}{glossaries-manual}{Package Options}
+in the main \sty{glossaries} user manual.
Next, you need to enable the creation of the various external
-files that are needed to create the glossaries, lists of acronyms
-or symbols for your document. This is done using:
+files that are required by the indexing application. This is done using:
\begin{definition}
\cs{makeglossaries}
\end{definition}
@@ -124,11 +100,13 @@ where \meta{label} is a unique label used to identify the term.
The second argument, \meta{settings}, is a key=value comma
separated list that is used to set the required information for
the term. A full list of available keys can be found in
-\latexhtml{section~\ref{sec:newglosentry}}{\htmladdnormallink{\dq{Defining Glossary Entries}}{glossaries-manual.html#sec:newglosentry}}
+\xrsectionref{sec:newglosentry}{glossaries-manual}{Defining Glossary
+Entries}
+%\latexhtml{section~\ref{sec:newglosentry}}{\htmladdnormallink{\qt{Defining Glossary Entries}}{glossaries-manual.html#sec:newglosentry}}
in the main \sty{glossaries} user manual. The principle keys are
\gloskey{name} and \gloskey{description}.
-For example, to define the term \dq{electrolyte}:
+For example, to define the term \qt{electrolyte}:
\begin{verbatim}
\newglossaryentry{electrolyte}{name=electrolyte,
description={solution able to conduct electric current}}
@@ -143,7 +121,7 @@ plural=\oe sophagi}
\end{verbatim}
In this case the label is \texttt{oesophagus}. Note that in this
case, the plural has to be specified using the \gloskey{plural} key
-since it isn't formed by simply appending the letter \dq{s}.
+since it isn't formed by simply appending the letter \qt{s}.
When you define terms, it is important to remember that they will
be sorted by an external application that doesn't interpret \LaTeX\
@@ -151,8 +129,8 @@ commands. \app{Xindy} is a little more \TeX-aware than \app{makeindex}, but
for this example they will both mis-sort \verb|\oe sophagus|.
Xindy will ignore the \verb*|\oe | part and will sort it according
to \texttt{sophagus}, so it will be placed with the terms starting
-with an \dq{s}. \app{Makeindex}, on the other hand, will sort it according
-to \verb|\oe sophagus| which starts with a symbol (the backslash),
+with an \qt{s}. \app{Makeindex}, on the other hand, will sort it according
+to \verb*|\oe sophagus| which starts with a symbol (the backslash),
so it will end up in the symbol group. You therefore need to
specify how to sort the term:
\begin{verbatim}
@@ -161,22 +139,13 @@ description={canal from mouth to stomach},
plural=\oe sophagi,sort=oesophagus}
\end{verbatim}
Note, however, that if you use the \sty{inputenc} package and
-\app{xindy}, you can use the encoded character \texttt{\oe} rather than
+\app{xindy}, you can use the encoded character \texttt{œ} rather than
\cs{oe} and \app{xindy} will sort it correctly:
-\begin{latexonly}
\begin{verbatim}
\newglossaryentry{oesophagus}{name=œsophagus,
description={canal from mouth to stomach},
plural=œsophagi}
\end{verbatim}
-\end{latexonly}
-\begin{htmlonly}\par
-\begin{ttfamily}
-\cs{newglossaryentry}\{oesophagus\}\{name=\oe sophagus,\newline
-description=\{canal from mouth to stomach\},\newline
-plural=\oe sophagi\}
-\end{ttfamily}\par
-\end{htmlonly}
If the name starts with an accented character, the first character
must be grouped:
@@ -186,18 +155,10 @@ description={select group of people},
sort=elite}
\end{verbatim}
or
-\begin{latexonly}
\begin{verbatim}
\newglossaryentry{elite}{name={é}lite,
description={select group of people}}
\end{verbatim}
-\end{latexonly}
-\begin{htmlonly}\par
-\begin{ttfamily}
-\cs{newglossaryentry}\{elite\}\{name=\{\'e\}lite,\newline
-description=\{select group of people\}\}
-\end{ttfamily}\par
-\end{htmlonly}
The name can also be a symbol, but you will also need to specify
the sort key. For example:
@@ -220,8 +181,11 @@ in the glossary.
Once you have defined a term, you can use it in the document. The
\sty{glossaries} package provides a number of commands that are
-described in \latexhtml{section~\ref{sec:glslink}}{the section
-\htmladdnormallink{\dq{Links to Glossary Entries}}{glossaries-manual.html#sec:glslink}} in the main \sty{glossaries} user manual.
+described in \xrsectionref{sec:glslink}{glossaries-manual}{Links to
+Glossary Entries}
+%\latexhtml{section~\ref{sec:glslink}}{the section
+%\htmladdnormallink{\qt{Links to Glossary Entries}}{glossaries-manual.html#sec:glslink}}
+ in the main \sty{glossaries} user manual.
Here, I shall just cover the main commands:
\begin{definition}
\cs{gls}\marg{label}
@@ -256,8 +220,11 @@ bases or acids.
Note that these commands all have two optional arguments that
aren't discussed here, but they are
-described in \latexhtml{section~\ref{sec:glslink}}{the section
-\htmladdnormallink{\dq{Links to Glossary Entries}}{glossaries-manual.html#sec:glslink}} in the main \sty{glossaries} user manual.
+described in \xrsectionref{sec:glslink}{glossaries-manual}{Links to
+Glossary Entries}
+%\latexhtml{section~\ref{sec:glslink}}{the section
+%\htmladdnormallink{\qt{Links to Glossary Entries}}{glossaries-manual.html#sec:glslink}}
+in the main \sty{glossaries} user manual.
\textbf{Caveat:} don't use these commands in moving arguments, such
as those used by \cs{chapter}, \cs{section} and \cs{caption}.
@@ -265,8 +232,10 @@ You can, instead, use commands such as
\begin{definition}
\cs{glsentrytext}\marg{label}
\end{definition}
-See \latexhtml{section~\ref{sec:glsnolink}}{the section
-\htmladdnormallink{\dq{Using Glossary Terms Without Links}}{glossaries-manual.html#sec:glsnolink}}
+See \xrsectionref{sec:glsnolink}{glossaries-manual}{Using Glossary
+Terms Without Links}
+%\latexhtml{section~\ref{sec:glsnolink}}{the section
+%\htmladdnormallink{\qt{Using Glossary Terms Without Links}}{glossaries-manual.html#sec:glsnolink}}
in the main \sty{glossaries} user manual.
\section{Acronyms}
@@ -280,8 +249,10 @@ placed in a separate list of acronyms:
\usepackage[acronym]{glossaries}
\end{verbatim}
There are other options that govern how acronyms appear. For further
-details, see \latexhtml{section~\ref{sec:acronyms}}{the section
-\htmladdnormallink{\dq{Acronyms}}{glossaries-manual.html#sec:acronyms}} in
+details, see \xrsectionref{sec:acronyms}{glossaries-manual}{Acronyms}
+%\latexhtml{section~\ref{sec:acronyms}}{the section
+%\htmladdnormallink{\qt{Acronyms}}{glossaries-manual.html#sec:acronyms}}
+in
the main \sty{glossaries} user manual.
Acronyms must be defined before use and are defined using:
@@ -304,10 +275,14 @@ appear. For example:
A \gls{svm} was implemented.
\end{verbatim}
If this is the first time this term has been used, the above would
-produce:\par\vskip\baselineskip\noindent
-A support vector machine (svm) was implemented.\par\vskip\baselineskip\noindent
-otherwise it would produce:\par\vskip\baselineskip\noindent
-A svm was implemented.\par\vskip\baselineskip\noindent
+produce:
+\begin{display}
+A support vector machine (svm) was implemented.
+\end{display}
+otherwise it would produce:
+\begin{display}
+A svm was implemented.
+\end{display}
You can reset an acronym so that the next use fully
expands it again using:
\begin{definition}
@@ -318,8 +293,10 @@ or you can reset all acronyms using
\cs{glsresetall}
\end{definition}
For further details on resetting and unsetting acronyms, see
-\latexhtml{section~\ref{sec:glsunset}}{the section
-\htmladdnormallink{\dq{Unsetting and Resetting Entry Flags}}{glossaries-manual.html#sec:glsunset}}
+\xrsectionref{sec:glsunset}{glossaries-manual}{Unsetting and
+Resetting Entry Flags}
+%\latexhtml{section~\ref{sec:glsunset}}{the section
+%\htmladdnormallink{\qt{Unsetting and Resetting Entry Flags}}{glossaries-manual.html#sec:glsunset}}
in the main \sty{glossaries} user manual.
\section{Displaying the Glossary or List of Acronyms}
@@ -364,9 +341,11 @@ consult the front-end's documentation.
If you don't have Perl installed, you will need to call \app{makeindex}
or \app{xindy} explicitly. This is more complicated and is described in
-\latexhtml{section~\ref{sec:makeglossaries}}{the section
-\htmladdnormallink{\dq{Generating the Associated Glossary Files}}{glossaries-manual.html#sec:makeglossaries}} in the
-main \sty{glossaries} user manual.
+\xrsectionref{sec:makeglossaries}{glossaries-manual}{Generating the
+Associated Glossary Files}
+%\latexhtml{section~\ref{sec:makeglossaries}}{the section
+%\htmladdnormallink{\qt{Generating the Associated Glossary Files}}{glossaries-manual.html#sec:makeglossaries}}
+in the main \sty{glossaries} user manual.
\item Once you have successfully run the indexing application, you
need to build/\LaTeX\ your document again (see step~1).
@@ -376,8 +355,10 @@ Note that sometimes you may have to repeat steps~2 and~3.
The appearance of the glossary depends on the glossary style in
use. The default style uses the \env{description} environment,
but there are many other styles available. These are described
-in \latexhtml{section~\ref{sec:styles}}{the section
-\htmladdnormallink{\dq{Glossary Styles}}{glossaries-manual.html#sec:styles}} in the main \sty{glossaries} user manual.
+in \xrsectionref{sec:styles}{glossaries-manual}{Glossary Styles}
+%\latexhtml{section~\ref{sec:styles}}{the section
+%\htmladdnormallink{\qt{Glossary Styles}}{glossaries-manual.html#sec:styles}}
+in the main \sty{glossaries} user manual.
By default, a number or list of numbers will appear after each entry
in the glossary. This indicates the page (or pages)
on which the term was used. This list can be suppressed using
@@ -387,8 +368,11 @@ the \pkgopt{nonumberlist} package option:
\end{verbatim}
Further information can be found in the main \sty{glossaries}
-\latexhtml{user manual (\href{glossaries.pdf}{glossaries.pdf})}{\htmladdnormallink{user
-manual}{glossaries-manual.html}} and there is also an
-\htmladdnormallink{article on the glossaries package}{http://www.latex-community.org/index.php?option=com_content&view=article&id=263:glossaries-nomenclature-lists-of-symbols-and-acronyms&catid=55:latex-general&Itemid=114}
-on the \LaTeX\ Community's\latex{\footnote{\url{http://www.latex-community.org/}}} Know How section.
+\altdocref{user manual}{glossaries}{glossaries-manual}
+%\latexhtml{user manual (\href{glossaries.pdf}{glossaries.pdf})}{\htmladdnormallink{user
+%manual}{glossaries-manual.html}}
+and there is also an
+\href{http://www.latex-community.org/index.php?option=com_content&view=article&id=263:glossaries-nomenclature-lists-of-symbols-and-acronyms&catid=55:latex-general&Itemid=114}{article on the glossaries package}
+on the \urlfootref{http://www.latex-community.org/}{\LaTeX\ Community's}
+Know How section.
\end{document}