\documentclass[a4paper]{article}

\usepackage[colorlinks,pdfauthor={Nicola L.C. Talbot},
            pdftitle={Upgrading from the glossary package to 
            the glossaries package}]{hyperref}
\usepackage{html}
\usepackage{xr}

\externaldocument{glossaries}

\title{Upgrading from the glossary package to the glossaries
package}
\author{Nicola L.C. Talbot}

\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}}

%\begin{latexonly}
\newcommand*{\sty}[1]{\textsf{#1}}

\newsavebox\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}}
\end{tabular}%
\vskip\baselineskip\par\noindent\ignorespaces}

\newenvironment{newway}{\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{glossaries}}
\end{tabular}%
\vskip\baselineskip\par\noindent\ignorespaces}
%\end{latexonly}
\begin{htmlonly}
\newenvironment{oldway}{\par\begin{ttfamily}}{\end{ttfamily}\par}
\newenvironment{newway}{\par\begin{ttfamily}}{\end{ttfamily}\par}
\newcommand{\sty}[1]{\texttt{#1}}
\renewcommand{\LaTeX}{LaTeX}
\end{htmlonly}

\begin{document}
\maketitle
\tableofcontents

\begin{abstract}
The purpose of this document is to provide advice if you want
to convert a \LaTeX\ document from using the obsolete 
\sty{glossary} package to the replacement \sty{glossaries} package.
\end{abstract}

\section{Package Options}

When converting a document that currently uses the obsolete
\sty{glossary} package to the replacement \sty{glossaries} package,
it should be fairly obvious that the first thing you need to do is
replace \verb|\usepackage{glossary}| with
\verb|\usepackage{glossaries}|, however some of the package options
are different, so you may need to change those as well.
Table~\ref{tab:pkgopt} shows the mappings from the \sty{glossary} 
to the \sty{glossaries} package options.

\begin{table}[htbp]
\caption[Mappings]{Mappings from \sty{glossary} to \sty{glossaries} 
package options}
\label{tab:pkgopt}
\begin{center}
\begin{tabular}{ll}
\bfseries \sty{glossary} option & \bfseries \sty{glossaries} option\\
style=list & style=list\\
style=altlist & style=altlist\\
style=long,header=none,border=none,cols=2 & style=long\\
style=long,header=plain,border=none,cols=2 & style=longheader\\
style=long,header=none,border=plain,cols=2 & style=longborder\\
style=long,header=plain,border=plain,cols=2 & style=longheaderborder\\
style=long,header=none,border=none,cols=3 & style=long3col\\
style=long,header=plain,border=none,cols=3 & style=long3colheader\\
style=long,header=none,border=plain,cols=3 & style=long3colborder\\
style=long,header=plain,border=plain,cols=3 & style=long3colheaderborder\\
style=super,header=none,border=none,cols=2 & style=super\\
style=super,header=plain,border=none,cols=2 & style=superheader\\
style=super,header=none,border=plain,cols=2 & style=superborder\\
style=super,header=plain,border=plain,cols=2 & style=superheaderborder\\
style=super,header=none,border=none,cols=3 & style=super3col\\
style=super,header=plain,border=none,cols=3 & style=super3colheader\\
style=super,header=none,border=plain,cols=3 & style=super3colborder\\
style=super,header=plain,border=plain,cols=3 & style=super3colheaderborder\\
number=none & nonumberlist\\
number=\meta{counter name} & counter=\meta{counter name}\\
toc & toc\\
hypertoc & toc\\
hyper & \emph{no corresponding option}\\
section=true & section\\
section=false & \emph{no corresponding option}\\ 
acronym & acronym\\
global & \emph{no corresponding option}
\end{tabular}
\end{center}
\end{table}

\section{Defining new glossary types}

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{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
\begin{newway}
\cs{glossarystyle}\marg{new style list}
\end{newway}%
immediately before \verb|\printglossary[type=|\meta{type}\verb|]|, 
if the new glossary requires a different style to the main (default)
glossary.

The \meta{style list} optional argument can be converted to
\meta{new style list} using the same mapping given in 
Table~\ref{tab:pkgopt}.

For example, if your document contains the following:
\begin{verbatim}
\newglossarytype[nlg]{notation}{not}{ntn}[style=long,header]
\newcommand{\notationname}{Index of Notation}
\end{verbatim}
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
\begin{verbatim}
\glossarystyle{style=longheader}
\end{verbatim}
immediately prior to displaying this glossary new type.

Note that the glossary title is no longer specified using 
\cs{}\meta{glossary-type}\texttt{name} (except for \cs{glossaryname}
and \cs{acronymname}) but is instead specified in the \meta{title}
argument of \cs{newglossary}. The short title which is specified
in the \sty{glossary} package by the command 
\cs{short}\meta{glossary-name}\texttt{name} is now specified
using the \texttt{toctitle} key in the optional argument to
\cs{printglossary}.

\section{\cs{make}\meta{glossary name}}

All instances of \cs{make}\meta{glossary name} (e.g.\ 
\cs{makeglossary} and \cs{makeacronym}) should be replaced
by the single command \cs{makeglossaries}. For example, if
your document contained the following:
\begin{verbatim}
\makeglossary
\makeacronym
\end{verbatim}
then you should replace both lines with the single line:
\begin{verbatim}
\makeglossaries
\end{verbatim}

\section{Storing glossary information}

With the old \sty{glossary} package you could optionally store
glossary information for later use, or you could simply use
\cs{glossary} whenever you wanted to add information to the glossary.
With the new \sty{glossaries} package, the latter option is no longer
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!

The former approach requires substituting all instances of
\begin{oldway}
\cs{storeglosentry}\marg{label}\marg{gls-entry}
\end{oldway}%
with
\begin{newway}
\cs{newglossaryentry}\marg{label}\marg{gls-entry}
\end{newway}%
This should be fairly easy to do using the search and replace
facility in your editor (but see notes below).

If you have used the optional argument of \cs{storeglosentry}
(i.e.\ you have multiple glossaries) then you will need to
substitute
\begin{oldway}
\cs{storeglosentry}\oarg{gls-type}\marg{label}\marg{gls-entry}
\end{oldway}%
with
\begin{newway}
\cs{newglossaryentry}\marg{label}\verb|{|\meta{gls-entry},type=\meta{gls-type}\verb|}|
\end{newway}

The glossary entry information \meta{gls-entry} may also need 
changing. If \meta{gls-entry} contains any of \texttt{makeindex}'s 
special characters (i.e.\ \texttt{@} \texttt{!} \verb|"| or
\verb"|") then they should no longer be escaped with \verb'"'
since the \sty{glossaries} package deals with these characters
internally. For example, if your document contains the following:
\begin{verbatim}
\storeglosentry{card}{name={$"|\mathcal{S}"|$},
description={The cardinality of the set $\mathcal{S}$}}
\end{verbatim}
then you will need to replace it with:
\begin{verbatim}
\newglossaryentry{card}{name={$|\mathcal{S}|$},
description={The cardinality of the set $\mathcal{S}$}}
\end{verbatim}

The \texttt{format} and \texttt{number} keys available in
\cs{storeglosentry} are not available with \cs{newglossaryentry}.
Note also that the \sty{glossary} package allowed you to use
\cs{storeglosentry} in the document, but \cs{newglossaryentry}
may only be used in the preamble.

\section{Adding an entry to the glossary}

The \sty{glossary} package provided two basic means to add
information to the glossary: firstly, the term was defined
using \cs{storeglosentry} and the entries for that term were
added using \cs{useglosentry}, \cs{useGlosentry} and \cs{gls}.
Secondly, the term was added to the glossary using \cs{glossary}.
This second approach is unavailable with the \sty{glossaries}
package.

\subsection{\cs{useglosentry}}
\label{sec:useglosentry}

The \sty{glossary} package allows you to add information to the
glossary for a predefined term without producing any text
in the document using
\begin{oldway}
\cs{useglosentry}\oarg{old options}\marg{label}
\end{oldway}%
Any occurrences of this command will need to be replaced with
\begin{newway}
\cs{glsadd}\oarg{new options}\marg{label}
\end{newway}%
The \texttt{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 
\texttt{counter=}\meta{counter name} in \meta{new options}.

\subsection{\cs{useGlosentry}}

The \sty{glossary} package allows you to add information to the
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
\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 in section~\ref{sec:useglosentry} above.

\subsection{\cs{gls}}

Both the \sty{glossary} and the \sty{glossaries} packages define
the command \cs{gls}. In this case, the only thing you need to
change is the \texttt{number} key in the optional argument
to \texttt{counter}.

\subsection{\cs{glossary}}

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).

If you don't like the idea of continually scrolling back to the
preamble to type all your \cs{newglossaryentry} commands, you may
prefer to create a new file, in which to store all these commands,
and then input that file in your document's preamble. Most text
editors and front-ends allow you to have multiple files open, and
you can tab back and forth between them.

\section{Acronyms}

In the \sty{glossary} package, acronyms were treated differently
to glossary entries. This resulted in inconsistencies and sprawling
unmaintainable code. The new \sty{glossaries} package treats
acronyms in exactly the same way as normal glossary terms. In fact,
in the \sty{glossaries} package:
\begin{newway}
\cs{newacronym}\oarg{options}\marg{label}\marg{abbrv}\marg{long}
\end{newway}
is a shortcut for:
\begin{newway}
\cs{newglossaryentry}\marg{label}\{type=\cs{acronymtype},
name=\marg{abbrv},
description=\marg{long},
text=\marg{abbrv},
first=\{\meta{long} (\meta{abbrv})\},
plural=\{\meta{abbrv}s\},
firstplural=\{\meta{long}s (\meta{abbrv}s)\},
\meta{options}\}
\end{newway}

This is different to the \sty{glossary} package which set the
\texttt{name} key to \meta{long} (\meta{abbrv}) and allowed you
to set a description using the \texttt{description} key.  If you want 
your document to remain like this, you can redefine \cs{newacronym}
as follows:
\begin{verbatim}
\renewcommand{\newacronym}[4][]{%
\newglossaryentry{#2}{type=\acronymtype,
name={#4 (#3)},
text={#3},
first={#4 (#3)},
plural={#3s},
firstplural={#4s (#3s)},#1}}
\end{verbatim}
The \texttt{description} key will then need to be entered using the
optional argument.

For example, if your document originally had the following:
\begin{verbatim}
\newacronym{SVM}{Support Vector Machine}{description=Statistical
pattern recognition technique}
\end{verbatim}
Then you would need to redefine \cs{newacronym} as shown above,
and change the above to:
\begin{verbatim}
\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}

If you have used \cs{useacronym} instead of \cs{}\meta{acr-name},
then you will need to replace all occurrences of
\begin{oldway}
\cs{useacronym}\oarg{insert}\marg{acr-name}
\end{oldway}%
with
\begin{newway}
\cs{gls}\marg{label}\oarg{insert}
\end{newway}%
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}.  

\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, you can replace
\begin{oldway}
\cs{acrsh}\marg{acr-name}
\end{oldway}%
with
\begin{newway}
\cs{glsentrytext}\marg{label}
\end{newway}%
However the \sty{glossaries} package provides no direct equivalent
of \cs{acrln}. Instead it provides \cs{glsentryfirst} which
produces the ``first use'' text without adding an entry to the
glossary, or affecting the first use flag.

Alternatively, if you haven't changed the definition of
\cs{newacronym}, the long form by itself can be obtained using
\cs{glsentrydesc}, since by default the \texttt{description} key is
set to the long form (but read the notes in the \sty{glossaries} 
manual regarding the \texttt{sanitize} package option).

If you want to be able to set a description, and be able to 
independently access the description, the long form and the
short form, you can redefine \cs{newacronym} so that it uses 
the \texttt{symbol} key and use \cs{defglsdisplayfirst}
so that it uses this value on first use, as follows:
\begin{verbatim}
\renewcommand{\newacronym}[4][]{\newglossaryentry{#2}{%
name={#4 (#3)},
text={#3},
first={#4},
symbol={#3},
}}
\defglsdisplayfirst{\acronymtype}{##1 (##3)##4}
\end{verbatim}
As before, you can access the short name via 
\cs{glsentrytext}\marg{label}, but you can now access just the long
form via \cs{glsentryfirst}\marg{label} and the description via
\cs{glsentrydesc}\marg{label}.

See
\latexhtml{section~\ref*{sec:code:glslink} (}{the section }``Using
glossary entries in the text''\latex{)} of the \sty{glossaries}
manual for further details of how to use these commands.

\subsection{\cs{ifacronymfirstuse}}

The \sty{glossary} package command
\begin{oldway}
\cs{ifacronymfirstuse}\marg{acr-name}\marg{text1}\marg{text2}
\end{oldway}%
can be replaced by the \sty{glossaries} command:
\begin{newway}
\cs{ifglsused}\marg{label}\marg{text2}\marg{text1}
\end{newway}%
Note that \cs{ifglsused} evaluates the opposite condition to
that of \cs{ifacronymfirstuse} which is why the last two arguments
have been reversed.

\subsection{\cs{resetacronym} and \cs{unsetacronym}}

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.
To reset an acronym, you will need to replace:
\begin{oldway}
\cs{resetacronym}\marg{acr-name}
\end{oldway}%
with either
\begin{newway}
\cs{glsreset}\marg{label}
\end{newway}%
or
\begin{newway}
\cs{glslocalreset}\marg{label}
\end{newway}

To unset an acronym, you will need to replace:
\begin{oldway}
\cs{unsetacronym}\marg{acr-name}
\end{oldway}%
with either
\begin{newway}
\cs{glsunset}\marg{label}
\end{newway}%
or
\begin{newway}
\cs{glslocalunset}\marg{label}
\end{newway}

\section{Displaying the glossary}

The \sty{glossary} package provides the command \cs{printglossary}
(or \cs{print}\meta{type} for other glossary types) which
can be used to print individual glossaries. The \sty{glossaries}
package provides the command \cs{printglossaries} which 
will print all the glossaries which have been defined, or
\cs{printglossary}\oarg{options} to print individual glossaries.
So if you just have \cs{printglossary}, then you can leave it as
it is, but if you have, say:
\begin{verbatim}
\printglossary
\printglossary[acronym]
\end{verbatim}
or
\begin{verbatim}
\printglossary
\printacronym
\end{verbatim}
then you will need to either replace this with either
\begin{verbatim}
\printglossaries
\end{verbatim}
or 
\begin{verbatim}
\printglossary
\printglossary[type=\acronymtype]
\end{verbatim}

The \sty{glossary} package allows you to specify a short title
(for the table of contents and page header) by defining a command
of the form \cs{short}\meta{glossary-type}\texttt{name}. The
\sty{glossaries} package doesn't do this, but instead provides
the \texttt{toctitle} key which can be used in the optional
argument to \cs{printglossary}. For example, if you have created
a new glossary type called \texttt{notation}, and you had
defined
\begin{verbatim}
\newcommand{\shortnotationname}{Notation}
\end{verbatim}
then you would need to use the \texttt{toctitle} key:
\begin{verbatim}
\printglossary[type=notation,toctitle=Notation]
\end{verbatim}
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}

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. 
Remember also, that if you used the \texttt{makeglos} Perl script,
you will need to use the \texttt{makeglossaries} Perl script 
instead.

\end{document}
