summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-01-17 01:07:22 +0000
committerKarl Berry <karl@freefriends.org>2009-01-17 01:07:22 +0000
commit4619c8309b673808e4d13a3202d2c8d9f6374f5e (patch)
tree5140a9eeec6a7f7c5523e90208f6c908998fffc2 /Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex
parente55e7bf0fee958f96ac89ec9c2cdfd3b1a91f99a (diff)
glossaries 1.18
git-svn-id: svn://tug.org/texlive/trunk@11899 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex297
1 files changed, 198 insertions, 99 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex b/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex
index 12b63f036fc..eae0a6359ad 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex
@@ -11,12 +11,7 @@
\title{Upgrading from the glossary package to the glossaries
package}
\author{Nicola L.C. Talbot}
-\date{17th June 2008}
-
-\newcommand*{\meta}[1]{\textnormal{\textless\emph{#1}\textgreater}}
-\newcommand*{\marg}[1]{\texttt{\char`\{\meta{#1}\char`\}}}
-\newcommand*{\oarg}[1]{\texttt{[\meta{#1}]}}
-\newcommand*{\cs}[1]{\texttt{\char`\\#1}}
+\date{14th January 2009}
%\begin{latexonly}
\newcommand*{\sty}[1]{\textsf{#1}}
@@ -25,21 +20,22 @@ package}
\newcommand*{\dq}[1]{``#1''}
\newsavebox\waybox
-\newenvironment{oldway}{\begin{lrbox}{\waybox}
+\newenvironment{oldway}{\begin{lrbox}{\waybox}%
\begin{minipage}{0.98\linewidth}\ttfamily
-}{\end{minipage}\end{lrbox}\vskip\baselineskip\par\noindent
-\begin{tabular}{r}
-\fbox{\usebox\waybox}\\[4pt]\footnotesize\mbox{\sty{glossary}}
+\ignorespaces}{\end{minipage}\end{lrbox}\vskip\baselineskip\par\noindent
+\begin{tabular}{@{}r@{}}%
+\fbox{\usebox\waybox}\\[4pt]\footnotesize\mbox{\sty{glossary}}%
\end{tabular}%
-\vskip\baselineskip\par\noindent\ignorespaces}
+\vskip\baselineskip\par\noindent\ignorespacesafterend}
\newenvironment{newway}{\begin{lrbox}{\waybox}
\begin{minipage}{0.98\linewidth}\ttfamily
-}{\end{minipage}\end{lrbox}\vskip\baselineskip\par\noindent
-\begin{tabular}{r}
+\ignorespaces}{\end{minipage}\end{lrbox}\vskip\baselineskip\par\noindent
+\begin{tabular}{@{}r@{}}%
\fbox{\usebox\waybox}\\[4pt]\footnotesize\mbox{\sty{glossaries}}
\end{tabular}%
-\vskip\baselineskip\par\noindent\ignorespaces}
+\vskip\baselineskip\par\noindent\ignorespacesafterend}
+\newcommand*{\meta}[1]{\textnormal{$\langle$\emph{#1}$\rangle$}}
%\end{latexonly}
\begin{htmlonly}
\newenvironment{oldway}{\par\begin{ttfamily}}{\end{ttfamily}\par}
@@ -49,8 +45,13 @@ package}
\newcommand*{\key}[1]{\texttt{#1}}
\newcommand*{\pkgopt}[1]{\texttt{#1}}
\newcommand*{\dq}[1]{"#1"}
+\newcommand*{\meta}[1]{\textnormal{\textless\emph{#1}\textgreater}}
\end{htmlonly}
+\newcommand*{\marg}[1]{\texttt{\char`\{\meta{#1}\char`\}}}
+\newcommand*{\oarg}[1]{\texttt{[\meta{#1}]}}
+\newcommand*{\cs}[1]{\texttt{\char`\\#1}}
+
\begin{document}
\maketitle
\tableofcontents
@@ -61,6 +62,57 @@ to convert a \LaTeX\ document from using the obsolete
\sty{glossary} package to the replacement \sty{glossaries} package.
\end{abstract}
+\section{Why the Need for a New Package?}
+\label{whyglossaries}
+
+The \sty{glossary} package started out as an example in a tutorial,
+but I decided that I may as well package it up and upload it to CTAN.
+Unfortunately it was fairly rigid and unable to adapt well to the
+wide variation in glossary styles. Users began making requests for
+enhancements, but with each enhancement the code became more
+complicated and bugs crept in. Each fix in one place seemed to cause
+another problem elsewhere. In the end, it was taking up too much
+of my time to maintain, so I decided to replace it with a much
+better designed package. With the new \sty{glossaries} package:
+
+\begin{itemize}
+\item you can define irregular plurals;
+
+\item glossary terms can have an associated symbol in addition
+to the name and description;
+
+\item new glossary styles are much easier to design;
+
+\item you can add dictionaries to supply translations for the
+fixed names used in headings and by some of the glossary styles;
+
+\item you can choose\footnote{as from v1.17. Previous versions
+were designed to be used with \texttt{makeindex} only} between using
+\texttt{makeindex} or \texttt{xindy} to sort the glossary. Using
+\texttt{xindy} means that:
+
+ \begin{itemize}
+ \item there is much better support for terms containing accented
+ or non-Latin characters;
+
+ \item there is support for non-standard location numbers;
+ \end{itemize}
+
+\item you don't need to remember to escape \texttt{makeindex}'s
+special characters as this is done internally;
+
+\item hierarchical entries and homographs are supported;\footnote{as
+from v1.17}
+
+\item there is better support for cross-referencing glossary entries;
+
+\item acronyms are just another glossary term which helps to
+maintain consistency;
+
+\item different acronym styles are supported.
+
+\end{itemize}
+
\section{Package Options}
When converting a document that currently uses the obsolete
@@ -115,22 +167,23 @@ global & \emph{no corresponding option}
If you have created new glossary types, you will need to
replace all instances of
\begin{oldway}
-\cs{newglossarytype}\oarg{log-ext}\marg{type}\marg{out-ext}\marg{in-ext}\oarg{style list}\newline
+\cs{newglossarytype}\oarg{log-ext}\marg{type}\marg{out-ext}\marg{in-ext}\oarg{old style list}\newline
\cs{newcommand}\verb|{\|\meta{type}name\verb|}|\marg{title}
\end{oldway}%
with
\begin{newway}
\cs{newglossary}\oarg{log-ext}\marg{type}\marg{out-ext}\marg{in-ext}\marg{title}
\end{newway}%
-in the preamble, and
+in the preamble, and, if the new glossary requires a different style
+to the main (default) glossary, you will also need to put
\begin{newway}
\cs{glossarystyle}\marg{new style}
\end{newway}%
-immediately before \verb|\printglossary[type=|\meta{type}\verb|]|,
-if the new glossary requires a different style to the main (default)
-glossary.
+immediately before the glossary is displayed, or you can specify
+the style when you display the glossary using \cs{printglossary}
+(see below).
-The \meta{style list} optional argument can be converted to
+The \meta{old style list} optional argument can be converted to
\meta{new style} using the same mapping given in
Table~\ref{tab:pkgopt}.
@@ -143,12 +196,11 @@ You will need to replace the above two lines with:
\begin{verbatim}
\newglossary[nlg]{notation}{not}{ntn}{Index of Notation}
\end{verbatim}
-in the preamble, and
+in the preamble and
\begin{verbatim}
\glossarystyle{longheader}
\end{verbatim}
-immediately prior to displaying this glossary new type.
-
+immediately prior to displaying this glossary.
Alternatively, you can specify the style using the \key{style}
key in the optional argument of \cs{printglossary}. For example:
\begin{verbatim}
@@ -189,10 +241,11 @@ available.\footnote{mainly because having a key value list in
\cs{glossary} caused problems, but it also helps consistency.} If
you have stored all the glossary information using
\cs{storeglosentry}, then you will need to convert these commands
-into the equivalent \cs{newglossaryentry}. If you haven't used
-\cs{storeglosentry}, then you'll have a bit more work to do!
+into the equivalent \cs{newglossaryentry}. If you have only
+used \cs{glossary}, then see
+\latexhtml{section~\ref{sec:csglossary}}{\htmlref{later}{sec:csglossary}}.
-The former approach requires substituting all instances of
+Substitute all instances of
\begin{oldway}
\cs{storeglosentry}\marg{label}\marg{gls-entry}
\end{oldway}%
@@ -257,8 +310,8 @@ Any occurrences of this command will need to be replaced with
\cs{glsadd}\oarg{new options}\marg{label}
\end{newway}%
The \key{format} key in \meta{old options} remains the same
-in \meta{new options}, the \texttt{number=}\meta{counter name}
-key in \meta{old options} should be replaced with\linebreak
+in \meta{new options}. However the \texttt{number=}\meta{counter
+name} key in \meta{old options} should be replaced with
\texttt{counter=}\meta{counter name} in \meta{new options}.
\subsection{\cs{useGlosentry}}
@@ -268,12 +321,12 @@ glossary for a predefined term with the given text using
\begin{oldway}
\cs{useGlosentry}\oarg{old options}\marg{label}\marg{text}
\end{oldway}%
-Any occurrences if this command will need to be replaced with
+Any occurrences of this command will need to be replaced with
\begin{newway}
\cs{glslink}\oarg{new options}\marg{label}\marg{text}
\end{newway}%
The mapping from \meta{old options} to \meta{new options} is
-the same as that given \latexhtml{section~\ref{sec:useglosentry}
+the same as that given \latexhtml{in section~\ref{sec:useglosentry}
above}{\htmlref{above}{sec:useglosentry}}.
\subsection{\cs{gls}}
@@ -286,29 +339,30 @@ a final optional argument which can be used to insert text into the
automatically generated text.
\subsection{\cs{glossary}}
+\label{sec:csglossary}
When using the \sty{glossaries} package, you should not use
-\cs{glossary} directly.\footnote{This is because \cs{glossary} requires
-the argument to be in a specific format and doesn't use the
-\meta{key}=\meta{value} format that the old glossary package used. The
-new package's internal commands set this format, as well as escaping
-any of \texttt{makeindex}'s special characters, so although it is
-still possible to use \cs{glossary} with the new package, it's not
-recommended. If you persist in using \cs{glossary} with the new
-package, don't complain if things go wrong!} If, with the old
-package, you have opted to explicitly use \cs{glossary} instead of
-storing the glossary information with \cs{storeglosentry}, then
-converting from \sty{glossary} to \sty{glossaries} will be more
-time-consuming, although in the end, I hope you will see the
-benefits!\footnote{From the user's point of view, using \cs{glossary}
-throughout the document is time consuming, and if you use it more than
-once for the same term, there's a chance extra spaces may creep in
-which will cause \texttt{makeindex} to treat the two entries as
-different terms, even though they look the same in the document.} If
-you have used \cs{glossary} with the old glossary package, you will
-instead need to define the relevant glossary terms using
-\cs{newglossaryentry} and reference the terms using \cs{glslink},
-\cs{gls} (or \cs{glspl} etc).
+\cs{glossary} directly.\footnote{This is because \cs{glossary}
+requires the argument to be in a specific format and doesn't use the
+\meta{key}=\meta{value} format that the old glossary package used.
+The new package's internal commands set this format, as well as
+escaping any of \texttt{makeindex}'s or \texttt{xindy}'s special
+characters. What's more, the format has changed as from v1.17 to
+allow the new package to be used with either \texttt{makeindex} or
+\texttt{xindy}.} If, with the old package, you have opted to
+explicitly use \cs{glossary} instead of storing the glossary
+information with \cs{storeglosentry}, then converting from
+\sty{glossary} to \sty{glossaries} will be more time-consuming,
+although in the end, I hope you will see the benefits.\footnote{From
+the user's point of view, using \cs{glossary} throughout the
+document is time consuming, and if you use it more than once for the
+same term, there's a chance extra spaces may creep in which will
+cause \texttt{makeindex} to treat the two entries as different
+terms, even though they look the same in the document.} If you have
+used \cs{glossary} with the old glossary package, you will instead
+need to define the relevant glossary terms using
+\cs{newglossaryentry} and reference the terms using
+\cs{glsadd}, \cs{glslink}, \cs{gls} etc.
If you don't like the idea of continually scrolling back to the
preamble to type all your \cs{newglossaryentry} commands, you may
@@ -361,43 +415,18 @@ and change the acronym definition to:
\newacronym[description=Statistical pattern recognition
technique]{svm}{SVM}{Support Vector Machine}
\end{verbatim}
-You will also need to replace all occurrences of \cs{SVM} with
-\verb|\gls{svm}|. Alternatively, you can define \cs{SVM}:
-\begin{verbatim}
-\newcommand{\SVM}{\gls{svm}}
-\end{verbatim}
-Remember that generally \LaTeX\ ignores all spaces following command
-names that consist of a backslash followed by letters! For example,
-using the above definition of \cs{SVM}, the following will ignore
-the space after \cs{SVM}:
-\begin{verbatim}
-The \SVM is a statistical pattern recognition technique.
-\end{verbatim}
-Instead, you need to explicitly insert a space:
-\begin{verbatim}
-The \SVM\ is a statistical pattern recognition technique.
-\end{verbatim}
-However, \verb|\SVM['s]| is equivalent to \verb|\gls{svm}['s]|,
-so you can do, for example:
-\begin{verbatim}
-The \SVM['s] parameters are obtained via optimisation techniques.
-\end{verbatim}
-
-The \sty{xspace} package provides the command \cs{xspace} which can
-be used to insert a space after the command name if required. Some
-people prefer to use this at the end of the command definition so
-that they don't need to remember to insert an explicit space.
-For example, if we use the \sty{xspace} package, we could define
-\cs{SVM} as follows:
-\begin{verbatim}
-\newcommand{\SVM}{\gls{svm}\xspace}
-\end{verbatim}
-so now the following will have a space before the word \dq{is}:
-\begin{verbatim}
-The \SVM is a statistical pattern recognition technique.
-\end{verbatim}
-However, you can no longer do \verb|\SVM['s]|, as the \cs{xspace} is
-now in the way.
+You can then reference the acronym using any of the new referencing
+commands, such as \cs{gls} or \cs{glsadd}.
+
+With the old \sty{glossary} package, when you defined an
+acronym, it also defined a command \cs{}\meta{acr-name} which
+could be used to display the acronym in the text. So the
+above SVM example would create the command \cs{SVM} with the old
+package. In the new \sty{glossaries} package, the acronyms are just
+another type of glossary entry, so they are displayed using
+\cs{gls}\marg{label}. Therefore, in the above example, you will
+also need to replace all occurrences of \cs{SVM} with
+\verb|\gls{svm}|.
If you have used \cs{useacronym} instead of \cs{}\meta{acr-name},
then you will need to replace all occurrences of
@@ -412,13 +441,44 @@ Note that the starred versions of \cs{useacronym} and
\cs{}\meta{acr-name} (which make the first letter uppercase) should
be replaced with \cs{Gls}\marg{label}.
+Alternatively (as from v1.18 of the \sty{glossaries} package),
+you can use \cs{oldacronym} which uses the same syntax as
+the old \sty{glossary} package's \cs{newacronym} and also
+defines \cs{}\meta{acr-name}.
+For example, if your document originally had the following:
+\begin{oldway}
+\begin{verbatim}
+\newacronym{SVM}{Support Vector Machine}{description=Statistical
+pattern recognition technique}
+\end{verbatim}
+\end{oldway}
+then you can change this to:
+\begin{newway}
+\begin{verbatim}
+\oldacronym{SVM}{Support Vector Machine}{description=Statistical
+pattern recognition technique}
+\end{verbatim}
+\end{newway}
+You can then continue to use \cs{SVM}\@. However, remember that
+\LaTeX\ generally ignores spaces after command names that consist of
+alphabetical characters. You will therefore need to force a space
+after \cs{}\meta{acr-name}, unless you also load the \sty{xspace}
+package. (See \latexhtml{section~\ref*{sec:acronyms}}{the
+\htmladdnormallink{Acronyms}{glossaries-manual.html#sec:acronyms}
+section} of the \sty{glossaries} documentation for further
+details.) Note that \cs{oldacronym} uses its first argument to
+define the acronym's label (as used by commands like \cs{gls}), so
+in the above example, with the new \sty{glossaries} package,
+\cs{SVM} becomes a shortcut for \verb|\gls{SVM}| and \cs{SVM*}
+becomes a shortcut for \verb|\Gls{SVM}|.
+
\subsection{\cs{acrln} and \cs{acrsh}}
In the \sty{glossary} package, it is possible to produce the
long and short forms of an acronym without adding an entry to
the glossary using \cs{acrln} and \cs{acrsh}. With the
\sty{glossaries} package (provided you defined the acronym using
-\cs{newacronym} and provided you haven't redefined \cs{newacronym})
+\cs{newacronym} or \cs{oldacronym} and provided you haven't redefined \cs{newacronym})
you can replace
\begin{oldway}
\cs{acrsh}\marg{acr-name}
@@ -437,12 +497,15 @@ with
\end{newway}%
The \sty{glossaries} package also provides the related commands
\cs{acrshortpl} (plural short form) and \cs{acrlongpl} (plural long
-form) as well as upper case variations.
+form) as well as upper case variations. If you use the
+\sty{glossaries} \dq{shortcuts} package option, you can use
+\cs{acs} in place of \cs{acrshort} and \cs{acl} in place of
+\cs{acrlong}.
-See
-\latexhtml{section~\ref*{sec:code:glslink} (}{the section }\dq{Using
-glossary entries in the text}\latex{)} of the \sty{glossaries}
-manual for further details of how to use these commands.
+See \latexhtml{section~\ref*{sec:acronyms}}{the
+\htmladdnormallink{Acronyms}{glossaries-manual.html#sec:acronyms}
+section} of the \sty{glossaries} manual for further details of
+how to use these commands.
\subsection{\cs{ifacronymfirstuse}}
@@ -463,7 +526,7 @@ have been reversed.
The \sty{glossary} package allows you to reset and unset the
acronym flag which is used to determine whether the acronym has
been used in the document. The \sty{glossaries} package also
-provides a means to do this on either a local or global level.
+provides a means to do this on either a local or a global level.
To reset an acronym, you will need to replace:
\begin{oldway}
\cs{resetacronym}\marg{acr-name}
@@ -490,6 +553,31 @@ or
\cs{glslocalunset}\marg{label}
\end{newway}
+To reset all acronyms, you will need to replace:
+\begin{oldway}
+\cs{resetallacronyms}
+\end{oldway}
+with
+\begin{newway}
+\cs{glsresetall}[\cs{acronymtype}]
+\end{newway}
+or
+\begin{newway}
+\cs{glslocalresetall}[\cs{acronymtype}]
+\end{newway}
+To unset all acronyms, you will need to replace:
+\begin{oldway}
+\cs{unsetallacronyms}
+\end{oldway}
+with
+\begin{newway}
+\cs{glsunsetall}[\cs{acronymtype}]
+\end{newway}
+or
+\begin{newway}
+\cs{glslocalunsetall}[\cs{acronymtype}]
+\end{newway}
+
\section{Displaying the glossary}
The \sty{glossary} package provides the command \cs{printglossary}
@@ -509,7 +597,7 @@ or
\printglossary
\printacronym
\end{verbatim}
-then you will need to either replace this with either
+then you will need to replace this with either
\begin{verbatim}
\printglossaries
\end{verbatim}
@@ -538,16 +626,27 @@ The \sty{glossaries} package will ignore \cs{shortnotationname},
so unless you have used it elsewhere in the document, you may
as well remove the definition.
-\section{Using makeindex}
+\section{Processing Your Document}
If you convert your document from using the \sty{glossary} package
to the \sty{glossaries} package, you will need to delete any of
the additional files, such as the \texttt{.glo} file, that were
created by the \sty{glossary} package, as the \sty{glossaries}
-package uses a different \texttt{makeindex} style file.
+package uses a different format.
Remember also, that if you used the \texttt{makeglos} Perl script,
you will need to use the \texttt{makeglossaries} Perl script
-instead.
+instead. As from v1.17, the \sty{glossaries} package can be
+used with either \texttt{makeindex} or \texttt{xindy}. Since
+\texttt{xindy} was designed to be multilingual, the
+new \sty{glossaries} package is a much better option for
+non-English documents.
+
+For further information on using \texttt{makeglossaries},
+\texttt{makeindex} or \texttt{xindy} to create your glossaries, see
+\latexhtml{section~\ref*{sec:makeglossaries}}{the
+\htmladdnormallink{Generating the Associated Glossary
+Files}{glossaries-manual.html#sec:makeglossaries} section} of the
+\sty{glossaries} documentation.
\section{Troubleshooting}