diff options
author | Karl Berry <karl@freefriends.org> | 2009-01-17 01:07:22 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2009-01-17 01:07:22 +0000 |
commit | 4619c8309b673808e4d13a3202d2c8d9f6374f5e (patch) | |
tree | 5140a9eeec6a7f7c5523e90208f6c908998fffc2 /Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.tex | |
parent | e55e7bf0fee958f96ac89ec9c2cdfd3b1a91f99a (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.tex | 297 |
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} |