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