From 9144cd7fe8a83679a67b2739e85be044b997c4a7 Mon Sep 17 00:00:00 2001
From: Karl Berry
+
Upgrading from the glossary package to the +glossaries package +
+Nicola L.C. Talbot |
2016-01-24
Abstract
The purpose of this document is to provide advice if you want to +class="cmr-9">The purpose of this document is to provide advice if you want to convert a LEX document from using the obsolete glossary package to the +class="cmr-9">package to replacement the replacement glossaries package.
@@ -231,15 +252,15 @@ class="cmtt-10">\useglosentry@@ -268,13 +287,13 @@ href="#index">Index href="#top">Top
The 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 +class="cmss-10">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 glossaries package:
@@ -286,8 +305,8 @@ package:When converting a document that currently uses the obsolete glossary package to the replacement glossaries package, it should be fairly obvious that the first thing you need -to do is replace glossaries package, it should be fairly obvious that the first thing you +need to do is replace \usepackage{glossary} with \usepackage{glossaries}, however -some of the package options are different, so you may need to change those as -well. Table \usepackage{glossaries}
, +however some of the package options are different, so you may need to change those +as well. Table 1 shows the mappings from the glossary to the glossaries package options.
For example, if your document contains the following: - + - +
You will need to replace the above two lines with: - + - +
in the preamble and - + - +
then you should replace both lines with the single line: - + - +
If you have used the optional argument of \storeglosentry (i.e. you have multiple -glossaries) then you will need to substitute + id="dx1-6009"> (i.e. you have +multiple glossaries) then you will need to substitute
The glossary entry information ⟨gls-entry⟩ may also need changing. If ⟨" since the glossaries package deals with these characters internally. For example, if your document contains the following: - + - +
then you will need to replace it with: - + - +
⟩ should be replaced with counter=⟨counter name⟩ -in ⟨counter +name⟩ in ⟨new options⟩. - + - +
\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 - +store all these commands, and then input that file in your document’s preamble. + - -text editors and front-ends allow you to have multiple files open, and you can tab back -and forth between them. + +Most text editors and front-ends allow you to have multiple files open, and you can +tab back and forth between them.
glossary package which set the name key to ⟨long⟩ (⟨abbrv⟩) and -allowed you to set a description using the abbrv⟩) +and allowed you to set a description using the description key. If you still want to do this, -you can use the 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 key in the +optional argument of \newacronym.
For example, if your document originally had the following: - + - +
and change the acronym definition to: - + - +
You can then reference the acronym using any of the new referencing commands, such
-as You can then reference the acronym using any of the new referencing commands,
+such as \gls or \glsaddacr-name
\newacronym{SVM}{Support Vector Machine}{description=Statistical
pattern recognition technique} @@ -1214,9 +1235,9 @@ class="cmss-10">glossary then you can change this to:
\oldacronym{SVM}{Support Vector Machine}{description=Statistical
pattern recognition technique} @@ -1227,16 +1248,16 @@ class="cmss-10">glossaries
You can then continue to use \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 EX generally +ignores spaces after command names that consist of alphabetical characters. You will +therefore need to force a space after \⟨acr-name⟩, unless you also load the xspace package. -(See xspace +package. (See Acronyms of the glossaries documentation for further details.) Note that -glossaries documentation for further details.) Note +that \oldacronym uses its first argument to define the acronym’s label (as used by commands like \acrln and \acrsh. With -the . With the +glossaries package (provided you defined the acronym using \newacronym -or or +\oldacronym and provided you haven’t redefined \newacronym{⟨acr-name⟩}
See \unsetacronym
The 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 glossaries package -also provides a means to do this on either a local or a global level. To reset an acronym, -you will need to replace: +class="cmss-10">glossaries
+package also provides a means to do this on either a local or a global level. To reset +an acronym, you will need to replace:
or - + - +
then you will need to replace this with either - + - +
or - + - +
The glossary package allows you to specify a short title (for the table of contents and -page header) by defining a command of the form glossary package allows you to specify a short title (for the table of contents +and page header) by defining a command of the form \short⟨glossary-type⟩name. The @@ -1602,12 +1623,12 @@ class="cmss-10">toctitle
key which can be used in the optional argument to \printglossary. For example, if you have created a -new glossary type called . For example, if you have created +a new glossary type called notation, and you had defined - + - +then you would need to use the toctitle key: - + - +
If you convert your document from using the glossary package to the glossaries package, -you will need to delete any of the additional files, such as the glossaries +package, you will need to delete any of the additional files, such as the .glo file, that were -created by the file, that +were created by the glossary package, as the glossaries package uses a different format. Remember also, that if you used the makeglosmakeglossaries Perl script instead. As from v1.17, the glossaries package -can be used with either glossaries package can +be used with either makeindex or xindyTop
Please check the FAQ for the glossaries package if you have any problems. - - - -
A -
- F
-file types 1 G
-\glossary 19, 20, 21, 22, 23, 24, 25, 26, 27 I
-\ifacronymfirstuse 55, 56 4 M
-\makeacronym 59 8, 9, 10, 11, 12, 13, 14, 15, 16 N
-\newacronym 74, 75, 76, 77, 78 19 P
package options: R
-\resetacronym 109 S
-
-
-
-\shortnotationname 111 27 U
-\unsetacronym 121 29 X
xindy 132, 133, 134, 135, 136, 137, 138 1as from v1.17. Previous versions were designed to be used with 4This is because \glossary requires the argument to be in a specific format and doesn’t use the
-⟨requires the argument to be in a specific format and doesn’t use
+the ⟨key⟩=⟨value⟩ format that the old glossary package used. The new package’s internal commands set this
+class="cmr-8">format that the old glossary package used. The new package’s internal commands set
format, as well as escaping any of this format, as well as escaping any of makeindex’s or xindy’s special characters. What’s more, the format
+class="cmr-8">’s special characters. What’s more, the
has changed as from v1.17 to allow the new package to be used with either format has changed as from v1.17 to allow the new package to be used with either makeindex or
@@ -2052,12 +1867,12 @@ class="cmr-8">and if you use it more than once for the same term, there’s
class="cmr-8">will cause makeindex to treat the two entries as different terms, even though they look the same in the
+class="cmr-8">to treat the two entries as different terms, even though they look the same in
document.
+
.glo 18
-
+
-\glossaryname 28
-\glossarystyle 29
-\Gls 30
-\gls 31, 32, 33, 34, 35, 36, 37, 38
\gls options
+
+
+
counter 39
+href="glossary2glossaries.html#dx1-10003" >2
number 40
-\glsadd 41, 42, 43
+href="glossary2glossaries.html#dx1-10002" >3
\glsadd options
counter 44
-\glslink 45, 46
-\glslocalreset 47
-\glslocalresetall 48
-\glslocalunset 49
-\glslocalunsetall 50
-\glsreset 51
-\glsresetall 52
-\glsunset 53
-
-
-
-\glsunsetall 54
-
-\ifglsused 57, 58
-
+
makeglos 60
+href="glossary2glossaries.html#dx1-17002" >5
makeglossaries 61, 62
-\makeglossaries 63
-\makeglossary 64
+href="glossary2glossaries.html#dx1-17003" >6, 7
makeindex 65, 66, 67, 68, 69, 70, 71, 72, 73
-
+
-\newglossary 79, 80
-\newglossaryentry 81, 82, 83, 84, 85, 86, 87
\newglossaryentry options
description 88, 89
+href="glossary2glossaries.html#dx1-12004" >17, 18
name 90
-\newglossarytype 91
-
+
description 95, 96
-\printglossaries 97
-\printglossary 98, 99, 100, 101, 102, 103, 104
+href="glossary2glossaries.html#dx1-12005" >20, 21
\printglossary options
style 105
+href="glossary2glossaries.html#dx1-4005" >22
toctitle 106, 107, 108
-
-\resetallacronyms 110
-
-\storeglosentry 112, 113, 114, 115, 116, 117, 118
\storeglosentry options
format 119
+href="glossary2glossaries.html#dx1-6013" >26
number 120
-
+
-\unsetallacronyms 122
-\useacronym 123, 124, 125
-\useGlosentry 126, 127
-\useglosentry 128, 129
\useglosentry options
format 130
+href="glossary2glossaries.html#dx1-8003" >28
number 131
-
+
+href="glossary2glossaries.html#dx1-2004" >30, 31, 32, 33, 34, 35, 36