diff options
author | Karl Berry <karl@freefriends.org> | 2008-03-07 19:18:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2008-03-07 19:18:57 +0000 |
commit | 65df837d29600b7980f1e49aa2bcee6da454bae0 (patch) | |
tree | dbd621ac42ed498c32fc49fb0bbe77753f1c32c1 /Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex | |
parent | b253317283f1d4cbf2a8c292bf3814b714e43ab3 (diff) |
glossaries update, including makeglossaries.bat in bin/win32 (4mar08)
git-svn-id: svn://tug.org/texlive/trunk@6879 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.tex | 529 |
1 files changed, 529 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex b/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex new file mode 100644 index 00000000000..f811c671f11 --- /dev/null +++ b/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex @@ -0,0 +1,529 @@ +\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} |