summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-06-01 23:39:05 +0000
committerKarl Berry <karl@freefriends.org>2009-06-01 23:39:05 +0000
commit0c13c2fa41ec19c3844414c339528abe82a9cd79 (patch)
treeef475ebee484639f9162b6cb4fc503ff7a19b744 /Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
parenta8d496072399303044632adc3815973fe69ff748 (diff)
glossaries 2.01 (1jun09)
git-svn-id: svn://tug.org/texlive/trunk@13568 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.tex371
1 files changed, 371 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex b/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
new file mode 100644
index 00000000000..cbfd8b0914f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/glossaries/glossariesbegin.tex
@@ -0,0 +1,371 @@
+\documentclass[a4paper,12pt]{article}
+
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{cmap}
+\usepackage{mathpazo}
+\usepackage[scaled=.90]{helvet}
+\usepackage{courier}
+\usepackage{xr-hyper}
+\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{30th May 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}
+
+\begin{document}
+\maketitle
+\tableofcontents
+
+\begin{abstract}
+This document is a brief guide to the \sty{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}}.
+\end{abstract}
+
+\section{What Do I Need?}
+
+You need to have the \sty{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}.
+\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
+\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.
+
+\section{Getting Started}
+
+The most obvious things to do is to remember to load the
+\sty{glossaries} package:
+\begin{verbatim}
+\usepackage{glossaries}
+\end{verbatim}
+Note that the \sty{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},
+\sty{babel} and \sty{ngerman}.
+
+If you want to use \app{xindy} rather than \app{makeindex} to sort the
+glossaries, you need to specify this in the package options:
+\begin{verbatim}
+\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.
+
+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:
+\begin{definition}
+\cs{makeglossaries}
+\end{definition}
+
+\section{Defining a Term or Symbol}
+
+You must define terms or symbols before you can use them in the
+document. This is best done in the preamble. Each term is defined
+using:
+\begin{definition}
+\cs{newglossaryentry}\marg{label}\marg{settings}
+\end{definition}
+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}}
+in the main \sty{glossaries} user manual. The principle keys are
+\gloskey{name} and \gloskey{description}.
+
+For example, to define the term \dq{electrolyte}:
+\begin{verbatim}
+\newglossaryentry{electrolyte}{name=electrolyte,
+description={solution able to conduct electric current}}
+\end{verbatim}
+In the above example, the label and the name happen to be the same.
+In the next example, the name contains a ligature but the label
+doesn't:
+\begin{verbatim}
+\newglossaryentry{oesophagus}{name=\oe sophagus,
+description={canal from mouth to stomach},
+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}.
+
+When you define terms, it is important to remember that they will
+be sorted by an external application that doesn't interpret \LaTeX\
+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),
+so it will end up in the symbol group. You therefore need to
+specify how to sort the term:
+\begin{verbatim}
+\newglossaryentry{oesophagus}{name=\oe sophagus,
+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
+\cs{oe} and \app{xindy} will sort it correctly:
+\begin{verbatim}
+\newglossaryentry{oesophagus}{name=œsophagus,
+description={canal from mouth to stomach},
+plural=œsophagi}
+\end{verbatim}
+
+If the name starts with an accented character, the first character
+must be grouped:
+\begin{verbatim}
+\newglossaryentry{elite}{name={\'e}lite,
+description={select group of people},
+sort=elite}
+\end{verbatim}
+or
+\begin{verbatim}
+\newglossaryentry{elite}{name={é}lite,
+description={select group of people}}
+\end{verbatim}
+
+The name can also be a symbol, but you will also need to specify
+the sort key. For example:
+\begin{verbatim}
+\newglossaryentry{pi}{name={\ensuremath{\pi}},
+description={ratio of circumference of circle to its
+diameter},sort=pi}
+\end{verbatim}
+It's also possible to have a name and a symbol. For example:
+\begin{verbatim}
+\newglossaryentry{set}{name=set,
+description={a collection of objects},
+symbol={\ensuremath{\mathcal{S}}}}
+\end{verbatim}
+Note, however, that not all glossary styles display the symbol
+in the glossary.
+
+\section{Using a Term}
+
+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.
+Here, I shall just cover the main commands:
+\begin{definition}
+\cs{gls}\marg{label}
+\end{definition}
+This prints the term associated with \meta{label}. Using the
+example in the previous section, \verb|\gls{oesophagus}|
+will display \oe sophagus. If the \sty{hyperref} package has also
+been loaded, the term will also be hyperlinked to the relevant
+entry in the glossary.
+\begin{definition}
+\cs{glspl}\marg{label}
+\end{definition}
+This prints the plural of the term associated with \meta{label},
+so \verb|\glspl{oesophagus}| will display \oe sophagi. Again, the
+text will be a hyperlink to the relevant entry in the glossary, if
+hyperlinks are defined.
+
+There are also versions that convert the first character to upper
+case if you need to start a sentence with a term:
+\begin{definition}
+\cs{Gls}\marg{label}
+\end{definition}
+and
+\begin{definition}
+\cs{Glspl}\marg{label}
+\end{definition}
+For example:
+\begin{verbatim}
+\Glspl{electrolyte} usually exist as solutions of salts,
+bases or acids.
+\end{verbatim}
+
+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.
+
+\textbf{Caveat:} don't use these commands in moving arguments, such
+as those used by \cs{chapter}, \cs{section} and \cs{caption}.
+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}}
+in the main \sty{glossaries} user manual.
+
+\section{Acronyms}
+
+The \sty{glossaries} package also allows you to define acronyms.
+By default, acronyms will be added to the main glossary, but if
+you use the \pkgopt{acronym} package option, acronyms will be
+placed in a separate list of acronyms:
+\begin{verbatim}
+\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
+the main \sty{glossaries} user manual.
+
+Acronyms must be defined before use and are defined using:
+\begin{definition}
+\cs{newacronym}\marg{label}\marg{abbrv}\marg{full}
+\end{definition}
+where \meta{label} is the label identifying the acronym, \meta{abbrv}
+is the abbreviated form and \meta{full} is the fully expanded text.
+For example:
+\begin{verbatim}
+\newacronym{label}{svm}{support vector machine}
+\end{verbatim}
+
+Once the acronym is defined, it can be used in the same way as
+any other glossary term with commands such as \cs{gls} and
+\cs{glspl}. On first use, the default will display \meta{full}
+(\meta{abbrv}). On subsequent use, only the abbreviation will
+appear. For example:
+\begin{verbatim}
+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
+You can reset an acronym so that the next use fully
+expands it again using:
+\begin{definition}
+\cs{glsreset}\marg{label}
+\end{definition}
+or you can reset all acronyms using
+\begin{definition}
+\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}}
+in the main \sty{glossaries} user manual.
+
+\section{Displaying the Glossary or List of Acronyms}
+
+In order to display the sorted list of terms, you first need to
+use
+\begin{definition}
+\cs{printglossaries}
+\end{definition}
+at the place where you want the glossary/list of acronyms to appear.
+Note that \cs{printglossaries} won't produce any text the first
+time you create your document, as an external indexing application
+needs to be used to sort and collate the entries. Creating the
+completed document is therefore \emph{at least} a three step
+process.
+
+Suppose your document is called \texttt{myDoc.tex}, then you need
+to:
+\begin{enumerate}
+\item Build/\LaTeX\ your document, either by clicking on an
+appropriate button in your front-end/text editor or by typing the
+following at a terminal/command prompt:
+\begin{verbatim}
+latex myDoc
+\end{verbatim}
+
+\item Run the indexing application on the external file(s) created
+by the \sty{glossaries} package. If you have used the \pkgopt{xindy}
+package option, you must use \app{xindy}, otherwise you must use
+\app{makeindex}. The \sty{glossaries} package comes with a convenient
+Perl wrapper that calls the appropriate indexing application the
+required number of times with the required options. If you have Perl
+installed, all you need to do is type
+\begin{verbatim}
+makeglossaries myDoc
+\end{verbatim}
+in a terminal or command prompt. If you are using a front-end (such
+as WinEdt or TeXnicCenter) and you want it to automatically run
+makeglossaries when you build your document, you will need to
+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.
+
+\item Once you have successfully run the indexing application, you
+need to build/\LaTeX\ your document again (see step~1).
+\end{enumerate}
+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.
+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
+the \pkgopt{nonumberlist} package option:
+\begin{verbatim}
+\usepackage[nonumberlist]{glossaries}
+\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.
+\end{document}