summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2008-03-07 19:18:57 +0000
committerKarl Berry <karl@freefriends.org>2008-03-07 19:18:57 +0000
commit65df837d29600b7980f1e49aa2bcee6da454bae0 (patch)
treedbd621ac42ed498c32fc49fb0bbe77753f1c32c1 /Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex
parentb253317283f1d4cbf2a8c292bf3814b714e43ab3 (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.tex529
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}