From 2591d5bab21119052bb58e82db7fd9fab8e97a7c Mon Sep 17 00:00:00 2001 From: Manuel Pégourié-Gonnard Date: Sat, 21 Jun 2008 16:05:24 +0000 Subject: glossaries update 21jun08 git-svn-id: svn://tug.org/texlive/trunk@8904 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/latex/glossaries/glossary2glossaries.html | 192 ++++++++++++--------- 1 file changed, 112 insertions(+), 80 deletions(-) (limited to 'Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.html') diff --git a/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.html b/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.html index 74207fb56c1..77571dcf832 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.html +++ b/Master/texmf-dist/doc/latex/glossaries/glossary2glossaries.html @@ -26,6 +26,7 @@ package">

Upgrading from the glossary package to the glossaries package

Nicola L.C. Talbot

+

17th June 2008


@@ -34,42 +35,44 @@ Contents

@@ -104,7 +107,7 @@ to the glossaries package options.

- +
Table 1: Mappings from glossary to glossaries @@ -221,7 +224,7 @@ with in the preamble, and

-\glossarystyle{<new style list>} +\glossarystyle{<new style>}

immediately before \printglossary[type=<type>], if the new glossary requires a different style to the main (default) @@ -229,7 +232,7 @@ glossary.

The <style list> optional argument can be converted to -<new style list> using the same mapping given in +<new style> using the same mapping given in Table 1.

@@ -244,10 +247,17 @@ You will need to replace the above two lines with: in the preamble, and

-\glossarystyle{style=longheader}
+\glossarystyle{longheader}
 
immediately prior to displaying this glossary new type. +

+Alternatively, you can specify the style using the style +key in the optional argument of \printglossary. For example: +

+\printglossary[type=notation,style=longheader]
+
+

Note that the glossary title is no longer specified using \<glossary-type>name (except for \glossaryname @@ -289,8 +299,8 @@ With the old glossary package you could optionally store glossary information for later use, or you could simply use \glossary whenever you wanted to add information to the glossary. With the new glossaries package, the latter option is no longer -available1. If +available.1 If you have stored all the glossary information using \storeglosentry, then you will need to convert these commands into the equivalent \newglossaryentry. If you haven't used @@ -344,9 +354,6 @@ description={The cardinality of the set $\mathcal{S}$}}

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

@@ -408,7 +415,7 @@ Any occurrences if this command will need to be replaced with \glslink[<new options>]{<label>}{<text>}

The mapping from <old options> to <new options> is -the same as that given in section 5.1 above. +the same as that given above.

@@ -420,7 +427,9 @@ the same as that given in section 2 If, with the old + HREF="#foot511">2 If, with the old package, you have opted to explicitly use \glossary instead of storing the glossary information with \storeglosentry, then converting from glossary to glossaries will be more time-consuming, although in the end, I hope you will see the benefits!3 If + HREF="#foot512">3 If you have used \glossary with the old glossary package, you will instead need to define the relevant glossary terms using \newglossaryentry and reference the terms using \glslink, @@ -462,7 +471,7 @@ In the glossary package, acronyms were treated differently to glossary entries. This resulted in inconsistencies and sprawling unmaintainable code. The new glossaries package treats acronyms in exactly the same way as normal glossary terms. In fact, -in the glossaries package: +in the glossaries package, the default definition of:

\newacronym[<options>]{<label>}{<abbrv>}{<long>} @@ -483,20 +492,10 @@ firstplural={<long>s (<abbrv>s)},

This is different to the glossary package which set the name key to <long> (<abbrv>) and allowed you -to set a description using the description key. If you want -your document to remain like this, you can redefine \newacronym -as follows: -

-\renewcommand{\newacronym}[4][]{%
-\newglossaryentry{#2}{type=\acronymtype,
-name={#4 (#3)},
-text={#3},
-first={#4 (#3)},
-plural={#3s},
-firstplural={#4s (#3s)},#1}}
-
-The description key will then need to be entered using the -optional argument. +to set a description using the description key. If you +still want to do this, you can use the description package +option, and use the description key in the +optional argument of \newacronym.

For example, if your document originally had the following: @@ -504,8 +503,12 @@ For example, if your document originally had the following: \newacronym{SVM}{Support Vector Machine}{description=Statistical pattern recognition technique} -Then you would need to redefine \newacronym as shown above, -and change the above to: +Then you would need to load the glossaries package using the +description package option, for example: +

+\usepackage[description]{glossaries}
+
+and change the acronym definition to:
 \newacronym[description=Statistical pattern recognition 
 technique]{svm}{SVM}{Support Vector Machine}
@@ -515,6 +518,39 @@ You will also need to replace all occurrences of \SVM with
 
 \newcommand{\SVM}{\gls{svm}}
 
+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 \SVM, the following will ignore +the space after \SVM: +
+The \SVM is a statistical pattern recognition technique.
+
+Instead, you need to explicitly insert a space: +
+The \SVM\ is a statistical pattern recognition technique.
+
+However, \SVM['s] is equivalent to \gls{svm}['s], +so you can do, for example: +
+The \SVM['s] parameters are obtained via optimisation techniques.
+
+ +

+The xspace package provides the command \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 xspace package, we could define +\SVM as follows: +

+\newcommand{\SVM}{\gls{svm}\xspace}
+
+so now the following will have a space before the word "is": +
+The \SVM is a statistical pattern recognition technique.
+
+However, you can no longer do \SVM['s], as the \xspace is +now in the way.

If you have used \useacronym instead of \<acr-name>, @@ -542,7 +578,9 @@ be replaced with \Gls{<label>}. In the glossary package, it is possible to produce the long and short forms of an acronym without adding an entry to the glossary using \acrln and \acrsh. With the -glossaries package, you can replace +glossaries package (provided you defined the acronym using +\newacronym and provided you haven't redefined \newacronym) +you can replace

\acrsh{<acr-name>} @@ -550,44 +588,26 @@ the glossary using \acrln and \acrsh. With the with

-\glsentrytext{<label>} +\acrshort{<label>}

-However the glossaries package provides no direct equivalent -of \acrln. Instead it provides \glsentryfirst which -produces the ``first use'' text without adding an entry to the -glossary, or affecting the first use flag. +and you can replace

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

+with

-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 \newacronym so that it uses -the symbol key and use \defglsdisplayfirst -so that it uses this value on first use, as follows: -

-\renewcommand{\newacronym}[4][]{\newglossaryentry{#2}{%
-name={#4 (#3)},
-text={#3},
-first={#4},
-symbol={#3},
-}}
-\defglsdisplayfirst{\acronymtype}{##1 (##3)##4}
-
-As before, you can access the short name via -\glsentrytext{<label>}, but you can now access just the long -form via \glsentryfirst{<label>} and the description via -\glsentrydesc{<label>}. +\acrlong{<label>} +

+The glossaries package also provides the related commands +\acrshortpl (plural short form) and \acrlongpl (plural long +form) as well as upper case variations.

See -the section ``Using -glossary entries in the text'' of the glossaries +the section "Using +glossary entries in the text" of the glossaries manual for further details of how to use these commands.

@@ -725,17 +745,29 @@ Remember also, that if you used the makeglos Perl script, you will need to use the makeglossaries Perl script instead. +

+ +

+9 Troubleshooting +

+ +

+Please check the FAQ +for the glossaries package if you have any +problems. +



Footnotes

-
... -available... +available.1
mainly because having a key value list in \glossary caused problems, but it also helps consistency.
-
... directly.... directly.2
This is because \glossary requires the argument to be in a specific format and doesn't use the @@ -747,7 +779,7 @@ recommended. If you persist in using \glossary with the new package, don't complain if things go wrong!
-
... +
... benefits!3
From the user's point of view, using \glossary -- cgit v1.2.3