Index of /CTAN/macros/latex/contrib/glossaries-extra

(1)

glossaries-extra.sty v1.49: an extension to the glossaries package

Nicola L.C. Talbot Dickimaw Books dickimaw-books.com

2022-10-14

This document is also available as HTML (glossaries-extra-manual.html).

Abstract

Theglossaries-extrapackage is an extension to theglossariespackage, provid- ing additional features. In particular, it provides a completely different abbreviation mechanism. You will need at leastglossariesversion 4.19, but it is best to update both packages at the same time, if new releases are available for both of them.

� Theglossaries-extrapackage uses a different set of defaults to the baseglossariespackage. This means that if you simply replaceglossarieswithglossaries-extrain an existing document, there may be some differences in the PDF, and you may encounter errors.

See §1.1 for more details.

� This document assumes some familiarity with theglossariespackage. If you are new toglossaries, you may prefer to start with the following:

• Theglossariespackage: a guide for beginners

� texdoc glossariesbegin

• glossaries-extraandbib2gls: an introductory guide

(2)

� texdoc bib2gls-begin

(3)

Symbols 598 Terms 599 Glossary Entry Keys Summary 605 Glossary Entry Fields Summary 614 \gls-Like and \glstext-Like Options Summary 616 Multi-Entry Set Options Summary 619 Print [Unsrt|noidx] Glossary Options Summary 624 Abbreviation Styles Summary 628 Glossary Styles Summary 645 Command Summary 652 Command Summary: @ . . . 652

Command Summary: A . . . 653

Command Summary: B . . . 663

Command Summary: C . . . 664

Command Summary: D . . . 667

Command Summary: E . . . 671

Command Summary: F . . . 672

Command Summary: G . . . 673

Command Summary: Glo . . . 674

Command Summary: Gls . . . 677

Command Summary: Glsxtr . . . 779

Command Summary: H . . . 894

(8)

Contents

Command Summary: I . . . 894

Command Summary: K . . . 898

Command Summary: L . . . 898

Command Summary: M . . . 899

Command Summary: N . . . 916

Command Summary: O . . . 919

Command Summary: P . . . 920

Command Summary: R . . . 930

Command Summary: S . . . 932

Command Summary: T . . . 934

Command Summary: U . . . 935

Command Summary: W . . . 937

Command Summary: X . . . 937

Command Summary: Z . . . 939

Environment Summary 940

Package Option Summary 941

Index 951

(9)

List of Examples

1. Multiple abbreviation styles . . . 42

2. \newabbreviationvs\newacronymvs\newglossaryentry . . . 46

3. @abbreviationvs@acronymvs@entry . . . 47

4. Referencing an abbreviation (withhyperref) . . . 49

5. First use of\glsvs\glsxtrfullvs\glsfirst. . . 51

6. Tagging abbreviation initials . . . 59

7. Category without an associated abbreviation style . . . 60

8. Theshort-nolongabbreviation style . . . 65

9. Theshort-nolong-descabbreviation style . . . 66

10. Thenolong-shortabbreviation style . . . 67

11. Theshort-sc-nolongabbreviation style . . . 68

12. Theshort-sc-nolong-descabbreviation style . . . 68

13. Thenolong-short-scabbreviation style . . . 69

14. Theshort-sm-nolongabbreviation style . . . 70

15. Theshort-sm-nolong-descabbreviation style . . . 70

16. Thenolong-short-smabbreviation style . . . 71

17. Theshort-em-nolongabbreviation style . . . 72

18. Theshort-em-nolong-descabbreviation style . . . 72

19. Thenolong-short-emabbreviation style . . . 73

20. Thelong-noshort-descabbreviation style . . . 74

21. Thelong-noshortabbreviation style . . . 75

22. Thelong-noshort-scabbreviation style . . . 76

23. Thelong-noshort-sc-descabbreviation style . . . 76

24. Thelong-noshort-smabbreviation style . . . 77

25. Thelong-noshort-sm-descabbreviation style . . . 78

26. Thelong-noshort-emabbreviation style . . . 78

27. Thelong-noshort-em-descabbreviation style . . . 79

28. Thelong-em-noshort-emabbreviation style . . . 80

29. Thelong-em-noshort-em-descabbreviation style . . . 80

30. Thelong-shortabbreviation style . . . 81

31. Thelong-short-descabbreviation style . . . 82

32. Thelong-short-scabbreviation style . . . 83

33. Thelong-short-sc-descabbreviation style . . . 84

34. Thelong-short-smabbreviation style . . . 84

35. Thelong-short-sm-descabbreviation style . . . 85

36. Thelong-short-emabbreviation style . . . 86

(10)

List of Examples

37. Thelong-short-em-descabbreviation style . . . 86

38. Thelong-em-short-emabbreviation style . . . 87

39. Thelong-em-short-em-descabbreviation style . . . 88

40. Thelong-short-userabbreviation style . . . 89

41. Thelong-short-user-descabbreviation style . . . 89

42. Thelong-postshort-userabbreviation style . . . 90

43. Thelong-postshort-user-descabbreviation style . . . 91

44. Thelong-postshort-sc-userabbreviation style . . . 92

45. Thelong-postshort-sc-user-descabbreviation style . . . 92

46. Theshort-longabbreviation style . . . 93

47. Theshort-long-descabbreviation style . . . 94

48. Theshort-sc-longabbreviation style . . . 95

49. Theshort-sc-long-descabbreviation style . . . 95

50. Theshort-sm-longabbreviation style . . . 96

51. Theshort-sm-long-descabbreviation style . . . 97

52. Theshort-em-longabbreviation style . . . 97

53. Theshort-em-long-descabbreviation style . . . 98

54. Theshort-em-long-emabbreviation style . . . 99

55. Theshort-em-long-em-descabbreviation style . . . 99

56. Theshort-long-userabbreviation style . . . 100

57. Theshort-long-user-descabbreviation style . . . 101

58. Theshort-postlong-userabbreviation style . . . 102

59. Theshort-postlong-user-descabbreviation style . . . 103

60. Thelong-hyphen-short-hyphenabbreviation style . . . 104

61. Thelong-hyphen-postshort-hyphenabbreviation style . . . 105

62. Thelong-hyphen-short-hyphen-descabbreviation style . . . 106

63. Thelong-hyphen-postshort-hyphen-descabbreviation style . . . 106

64. Thelong-hyphen-noshort-desc-noregabbreviation style . . . 107

65. Thelong-hyphen-noshort-noregabbreviation style . . . 108

66. Theshort-hyphen-long-hyphenabbreviation style . . . 109

67. Theshort-hyphen-postlong-hyphenabbreviation style . . . 109

68. Theshort-hyphen-long-hyphen-descabbreviation style . . . 110

69. Theshort-hyphen-postlong-hyphen-descabbreviation style . . . 111

70. Thelong-only-short-onlyabbreviation style . . . 112

71. Thelong-only-short-only-descabbreviation style . . . 112

72. Thelong-only-short-sc-onlyabbreviation style . . . 113

73. Thelong-only-short-sc-only-descabbreviation style . . . 114

74. Theshort-footnoteabbreviation style . . . 115

75. Theshort-footnote-descabbreviation style . . . 116

76. Theshort-postfootnoteabbreviation style . . . 117

77. Theshort-postfootnote-descabbreviation style . . . 118

78. Theshort-sc-footnoteabbreviation style . . . 119

79. Theshort-sc-footnote-descabbreviation style . . . 120

(11)

List of Examples

81. Theshort-sc-postfootnote-descabbreviation style . . . 122

82. Theshort-sm-footnoteabbreviation style . . . 123

83. Theshort-sm-footnote-descabbreviation style . . . 124

84. Theshort-sm-postfootnoteabbreviation style . . . 125

85. Theshort-sm-postfootnote-descabbreviation style . . . 126

86. Theshort-em-footnoteabbreviation style . . . 127

87. Theshort-em-footnote-descabbreviation style . . . 128

88. Theshort-em-postfootnoteabbreviation style . . . 129

89. Theshort-em-postfootnote-descabbreviation style . . . 130

90. Illustrating thepreresetoption . . . 192

91. Combiningpreresetandpreunset . . . 193

92. References in section headings (simplistic approach) . . . 203

93. References in section headings using\glsfmttext . . . 205

94. Reference with hyperlink in section headings . . . 206

95. Nested link text with\glspl . . . 233

96. Link text styles: outer, middle, inner, hyperlinks and post-link hook . . . 236

97. Link text styles: outer, middle, inner, hyperlinks and post-link hooks (custom and abbreviation style) . . . 238

98. Changing the outer text format . . . 239

99. Middle formatting . . . 240

100. Inner formatting . . . 242

101. Category post-link hook . . . 246

102. Category post-link hook with punctuation lookahead . . . 249

103. Category post-link hooks . . . 252

104. Location list ordering (makeindex) . . . 262

105. Location list ordering (bib2gls) . . . 263

106. Cross-references (autoseeindex=true) . . . 268

107. Cross-references (autoseeindex=false) . . . 269

108. Cross-references (autoseeindex=falseand post-name hook) . . . 270

109. Cross-references (nosee,seealsooralias) . . . 272

110. Cross-references (bib2gls) . . . 274

111. Cross-references (bib2glsandselection=recorded and deps and see) 275 112. Cross-references (bib2glsandselection=recorded and deps and see, prune-xr) . . . 276

113. Resetting the first use flag (\glsreset) . . . 282

114. Local unset . . . 283

115. Abbreviations withbeamer(unset buffering) . . . 288

116. Buffering first use unsets with\mbox . . . 289

117. Alternatives to buffering . . . 290

118. Foreign language field encapsulation . . . 295

119. Storing a formatting command in a field . . . 298

120. Formatting lists contained in field values . . . 303

121. Entry counting according to category . . . 312

(12)

List of Examples

123. Enabling unit counting to hook into hyperlink setting . . . 317

124. Link counting used to selectively suppress hyperlinks . . . 320

125. Multi-entries: hierarchical . . . 327

126. Multi-entries: hierarchical with first-use suffix . . . 328

127. Multi-entries: hierarchical with category suffix . . . 329

128. Multi-entries: separators . . . 330

129. Multi-entries: skipping elements . . . 332

130. Multi-entries: skipping elements (unsetting others) . . . 333

131. Multi-entries: skipping elements (prefix and post-link hooks) . . . 337

132. Changing the target prefix . . . 380

133. Prepending to the target prefix for just the entry item . . . 381

134. Displaying unsorted glossaries . . . 384

135. Displaying unsorted glossaries withstylemods . . . 385

136. Displaying unsorted glossaries with different group settings . . . 386

137. Displaying unsorted glossaries with a copied list . . . 388

138. Displaying unsorted glossaries with custom groups . . . 392

139. Displaying unsorted glossaries with custom groups and sub-group headings 393 140. Displaying sorted glossaries with groups usingbib2gls . . . 397

141. Filtering by category . . . 403

142. Inner glossaries usingprintunsrtglossarywrap . . . 405

143. Nested glossaries . . . 406

144. Sub-glossary for a given counter value . . . 411

145. Sub-glossary for a given counter value ordered by use in the section . . . 413

146. Thebookindexstyle . . . 438

147. Thetopicstyle . . . 462

148. Thetopicmcolsstyle . . . 463

149. Thetopicmcolsstyle with the widest name set . . . 464

150. Two entries per row with\printunsrttable . . . 474

151. Usingbib2gls: one resource set . . . 516

152. Usingbib2gls: multiple resource sets . . . 518

153. Usingbib2gls: sub-blocks . . . 520

154. Usingbib2gls: record counting . . . 528

155. Usingbib2gls: unit record counting . . . 531

156. Usingbib2gls: unit record counting mini-glossary . . . 533

157. Usingbib2gls: simple custom sort rule . . . 538

158. Usingbib2gls: dual backlinks . . . 562

159. Usingbib2gls: dual entry label prefixes . . . 570

(13)

Part I.

User Guide

(14)

1. Introduction

Theglossariespackage is a flexible package, but it’s also a heavy-weight package that uses a lot of resources. As package developer, I’m caught between those users who complain about the drawbacks of a heavy-weight package with a large user manual and those users who want more features (which necessarily adds to the package weight and manual size).

Theglossaries-extrapackage is an attempt to provide a compromise for this conflict. Ver- sion 4.22 of theglossariespackage is the last version to incorporate any major new features.

Future versions ofglossarieswill mostly just be bug fixes. New features will instead be added toglossaries-extra. This means that the base glossariespackage won’t increase in terms of package loading time and allocation of resources, but those users who do want extra features available will have more of a chance of getting their feature requests accepted.

� Some of the commands provided by the baseglossariespackage are incompatible with glossaries-extra. These are marked with�in this document.

Theglossaries-extrapackage internally loads theglossariespackage. As a general rule, it’s better to defer loading the baseglossariespackage toglossaries-extrarather than loading the two packages separately.

1.1. Package Defaults

I’m not happy with some of the default settings assumed by theglossariespackage, and, judg- ing from code I’ve seen, other users also seem unhappy with them, as certain package options are often used in questions posted on various sites. I can’t change the default behaviour of glossariesas it would break backward compatibility, but sinceglossaries-extrais a separate package, I have decided to implement some of these commonly-used options by default. You can switch them back if they’re not appropriate.

The new defaults are:

• toc=true(add the glossaries to the table of contents). Usetoc=false to switch this back off.

• nopostdot=true(suppress the terminating full stop after the description in the glossary).

Usenopostdot=false or justpostdotto restore the terminating full stop. Alterna- tively, if you are interested in switching tobib2gls, you can instructbib2glsto insert it with thepost-description-dotoption.

(15)

1. Introduction

• noredefwarn (suppress the warnings that occur when the theglossary environment and \printglossaryare redefined whileglossariesis loading). Note that this won’t have any effect if the glossariespackage has already been loaded before you load the glossaries-extrapackage.

• If babelhas been loaded, the translate=babel option is switched on. To revert to using thetranslatorinterface, usetranslate=true. There is no change to the default ifbabelhasn’t been loaded.

• The default style used by\newacronymisshort-nolong. (That is, the long form is not shown on first use.) To revert back to “hlongi(hshorti)” on first use do:

�

\setabbreviationstyle[acronym]{long-short}

In the above example, long-short refers to theglossaries-extraabbreviation style not theglossariesacronym style of the same name. See §4 for further details.

1.2. Example Differences Between glossaries and glossaries-extra

The examples below illustrate the difference in explicit package options betweenglossaries andglossaries-extra. There may be other differences resulting from modifications to commands provided byglossaries.

1.2.1. Basic defaults

�

\documentclass{article}

\usepackage{glossaries-extra}

This is like:

�

\usepackage[toc,nopostdot]{glossaries}

(16)

1. Introduction

1.2.2. Language defaults

�

\documentclass[british]{article}

\usepackage{babel}

This is like:

�

\documentclass[british]{article}

\usepackage{babel}

\usepackage[toc,nopostdot,translate=babel]{glossaries}

1.2.3. Combined with memoir

�

\documentclass{memoir}

This is like:

�

\usepackage[toc,nopostdot,noredefwarn]{glossaries}

However

�

\usepackage{glossaries}

This is like:

�

\usepackage[toc=false,nopostdot=false]{glossaries}

(17)

1. Introduction

Since by the timeglossaries-extrahas been loaded, the baseglossariespackage has already redefinedmemoir’s glossary-related commands.

1.2.4. Abbreviations

Abbreviations are defined with\newabbreviation:

�

\newabbreviation{svm}{SVM}{support vector machine}

\begin{document}

First use: \gls{svm}. Explicit full form: \glsxtrfull{svm}.

\end{document}

This is the closest match to:

�

\usepackage{glossaries}

\newacronym{svm}{SVM}{support vector machine}

\begin{document}

First use: \gls{svm}. Explicit full form: \acrfull{svm}.

\end{document}

If you want to continue using\newacronymthen you will need to change the style for the acronymcategory:

�

\newacronym{svm}{SVM}{support vector machine}

\begin{document}

First use: \gls{svm}. Explicit full form: \glsxtrfull{svm}.

\end{document}

� Don’t use commands like \glsfirst or \glstext with abbreviations. See §4 for further details.

1.2.5. Glossary Mid-Build Placeholder (\printglossary)

Another noticeable change withglossaries-extrais that by default\printglossarywill now display information text in the document if the external glossary file doesn’t exist. This is explanatory text to help new users who can’t work out what to do next to complete the

(18)

1. Introduction

document build. Once the document is set up correctly and the external files have been generated, this text will disappear.

This change is mostly likely to be noticed by users with one or more redundant empty glossaries who ignore transcript messages, explicitly usemakeindex/xindyon just the non- empty glossary (or glossaries) and use the iterative\printglossariescommand instead of

\printglossary. For example, consider the following:

�

\usepackage[acronym]{glossaries}

\makeglossaries

\newacronym{laser}{laser}{light amplification by stimulated emission of radiation}

\begin{document}

\gls{laser}

\printglossaries

\end{document}

The above document will only display the list of acronyms at the place where \print- glossariesoccurs. However it will also attempt to input theglsfile associated with the mainglossary.

If you usemakeglossaries, you’ll get the warning message:

Warning: File 'test.glo' is empty.

Have you used any entries defined in glossary 'main'?

Remember to use package option 'nomain' if you don't want to use the main glossary.

(where the original file is called test.tex) but if you simply call makeindex directly to generate theacrfile (without attempting to create theglsfile) then the transcript file will always contain the message:

No file test.gls.

This doesn’t occur withmakeglossariesas it will create theglsfile containing the single command\null.

If you simply change from glossaries to glossaries-extrain this document, you’ll find a change in the resulting PDF if you don’t use makeglossaries and you only generate the acrfile withmakeindex.

The transcript file will still contain the message about the missinggls, but now you’ll also see information in the actual PDF document. The simplest remedy is to follow the advice inserted into the document at that point, which is to add thenomainpackage option:

(19)

1. Introduction

�

\usepackage[nomain,acronym,postdot]{glossaries-extra}

\makeglossaries

\newacronym{laser}{laser}{light amplification by stimulated emission of radiation}

\begin{document}

\gls{laser}

\printglossaries

\end{document}

� Note the need to set the acronym style using\setabbreviationstylebefore\newacronym. See §4 for further details.

1.3. Further Reading

The following documents and web pages are also available:

• Theglossaries-extradocumented code

� texdoc glossaries-extra-code

• Gallery: glossaries,glossaries-extraandbib2gls.¹

• FAQs: glossaries,glossaries-extraandbib2gls.²

• Incorporatingmakeglossariesormakeglossaries-liteorbib2glsinto the document build.³

• Thebib2glsapplication.⁴

• Theglossariespackage.⁵

1dickimaw-books.com/gallery

2dickimaw-books.com/faq.php

3dickimaw-books.com/latex/buildglossaries/

4ctan.org/pkg/bib2gls

(20)

2. Package Options

�

\usepackage[hoptionsi]{glossaries-extra}

This chapter describes the package options provided byglossaries-extrathat are either not defined by the baseglossariespackage or are modified byglossaries-extra. You can additionally pass the base package options toglossaries-extra. For example, instead of:

�

\usepackage[nonumberlist]{glossaries}

\usepackage[abbreviations]{glossaries-extra}

you can simply do:

�

\usepackage[abbreviations,nonumberlist]{glossaries-extra}

� It’s better not to load the glossaries package first. Leave glossaries-extra to load it, where possible, to allow for a smoother integration between the two packages.

Afterglossaries-extrahas been loaded, some of theglossaries-extrapackage options may be changed with:

�

\glossariesextrasetup{hoptionsi}

wherehoptionsiare the same as the relevant package option.

� Certain options can only be supplied as package options since the settings need to be known whileglossaries-extrais loading.

To change the baseglossariespackage’s options (that may be changed after the package

(21)

2. Package Options

has loaded), continue to use:

�

\setupglossaries{hoptionsi}

but don’t use any of the options listed here in that command.

2.1. Glossary Lists

� nomissingglstext=hbooleani default: true;initial: false If true, this will suppress the warning written to the transcript and the warning text that will appear in the document if the external glossary files haven’t been generated due to an incomplete document build. However, it’s probably simpler just to fix whatever has caused the failure to build the external file or files.

� abbreviations

This option has no value and can’t be cancelled. If used, it will automatically create a new glossary with the labelabbreviationsand redefines\glsxtrabbrvtypeto this label. (The file extensions areglg-abr,gls-abrandglo-abr.) In addition, this option defines a shortcut command:

�

\printabbreviations[hoptionsi] which is equivalent to:

�

\printglossary[type=\glsxtrabbrvtype,hoptionsi]

Ifglossaries-extra-bib2glsis also loaded then this option will additionally provide\print- unsrtabbreviationswhich uses\printunsrtglossaryinstead.

The title of the new glossary is given by

�

\abbreviationsname initial: Abbreviations

If this command is already defined, it’s left unchanged. Otherwise it’s defined to “Abbrevi- ations” ifbabelhasn’t been loaded or\acronymnameif babelhas been loaded. However, if you’re usingbabelit’s likely you will need to change this. (See §15 for further details.)

(22)

2. Package Options

� If you don’t use theabbreviationspackage option, the\abbreviationsnamecom- mand won’t be defined (unless it’s defined by an included language file).

If theabbreviationsoption is used and the acronymoption provided by the glossaries package hasn’t been used, then \acronymtype will be set to \glsxtrabbrvtype so that acronyms defined with\newacronymcan be added to the list of abbreviations. If you want acronyms in themainglossary and other abbreviations in theabbreviationsglossary then you will need to redefine\acronymtypetomain:

�

\renewcommand*{\acronymtype}{main}

Note that there are no analogous options to theglossariespackage’sacronymlists option (or associated commands) as the abbreviation mechanism is handled differently with glossaries-extra.

� symbols

This is passed to the baseglossariespackage, butglossaries-extrawill additionally define:

�

\glsxtrnewsymbol[hkey=value listi]{hentry-labeli}{hsymi} which is equivalent to:

�

\newglossaryentry{hentry-labeli}{name={hsymboli},

sort={hentry-labeli},type={symbols},category={symbol}, hoptionsi}

Note that thesortkey is set to thehentry-labelinot thehsymbolias the symbol will likely contain commands. If this isn’t appropriate, you can override it by using thesortkey in the optional argument.

This option also sets theregularattribute totruefor thesymbolcategory and provides the category post-description hook:

�

\glsxtrpostdescsymbol initial: empty

Ifglossaries-extra-bib2glsis also loaded then this option will additionally provide\print-

(23)

2. Package Options

unsrtsymbolswhich uses\printunsrtglossary.

� numbers

This is passed to the baseglossariespackage butglossaries-extrawill additionally define:

�

\glsxtrnewnumber[hkey=value listi]{hentry-labeli}{hnumi} which is equivalent to:

�

\newglossaryentry{hentry-labeli}{name={hnumberi},

sort={hentry-labeli},type={numbers},category={number}, hoptionsi}

Note that thesortkey is set to thehentry-labeli. If this isn’t appropriate, you can override it by using thesortkey in the optional argument.

This option also sets theregularattribute totruefor thenumbercategory and provides the category post-description hook:

�

\glsxtrpostdescnumber initial: empty

Ifglossaries-extra-bib2glsis also loaded then this option will additionally provide\print- unsrtnumberswhich uses\printunsrtglossary.

acronyms �

This is passed to the baseglossariespackage (which defines\printacronymsand creates a new glossary with the labelacronym) but ifglossaries-extra-bib2glsis loaded then this option will additionally provide\printunsrtacronymswhich uses\printunsrtglossary.

As with the baseglossariespackage, this option redefines\acronymtypetoacronym. Note that this option doesn’t change\glsxtrabbrvtype.

� acronym=hbooleani default: true;initial: false Ifacronym=true, this behaves likeacronyms. Note thatacronym=falsewon’t work if the baseglossariespackage was loaded beforeglossaries-extra.

� index

(24)

2. Package Options

This is passed to the baseglossariespackage but ifglossaries-extra-bib2glsis loaded then this option will additionally provide\printunsrtindexwhich uses\printunsrtglossary.

The base packageindexoption also defines:

�

\newterm[hkey=value listi]{hentry-labeli}

This definition is modified byglossaries-extrato additionally set thecategorytoindexand sets thedescriptionto discard the post-description hook (\nopostdesc) but retain\gls- xtrpostdescriptionso that the category post-description hook can still be applied.

This option also sets theregularattribute totruefor theindexcategory and defines an associated category post-description hook:

�

\glsxtrpostdescindex initial: empty

2.2. Glossary Style Options

� nopostdot=hbooleani default: true;initial: true This option is provided byglossarieswhere it simply alters a corresponding conditional that’s used inside\glspostdescriptionto determine whether or not to insert a full stop.

The postpunc option (see below) redefines \glspostdescription, so the nopostdot option is modified byglossaries-extrato reset the hook back to its original definition to coun- teract any use of thepostpuncoption.

� This option will have no effect if the glossary style doesn’t include\glspostdescription. (Usestylemodsto ensure that all the predefined styles that show the description have this hook added.)

If you are using bib2gls, you may prefer to use the post-description-dotresource option.

� postdot

This is a shortcut fornopostdot=false.

� postpunc=hvaluei

(25)

2. Package Options

This option redefines\glspostdescriptionto display the required punctuation. Note that this means the hook will no longer check for thenopostdotconditional.

� This option will have no effect if the glossary style doesn’t include\glspostdescription. (Usestylemodsto ensure that all the predefined styles that show the description have this hook added.)

Thepostpuncvalue may either be the required punctuation or one of the following key- words:

� postpunc=dot

This redefines\glspostdescriptionto use a full stop but also adjusts the space factor. This isn’t exactly the same asnopostdot=falsesince it removes the conditional from\glspostdescription. If you are usingbib2gls, you may prefer to use thepost-description-dot resource option.

� postpunc=comma

This redefines\glspostdescriptionto a comma.

� postpunc=none

This redefines\glspostdescriptionto do nothing. This isn’t exactly the same asnopostdot

=truesince it removes the conditional from\glspostdescription.

�

stylemods=hvaluei default: default

Loads theglossaries-extra-stylemodspackage (see §8.6.5), which patches the styles provided with the baseglossaries package so that they all use \glspostdescription. Extra hooks are also provided to make them easier to customize. The value may be one of the following:

� stylemods=all

Loads all styles that are provided by bothglossariesandglossaries-extra.

� stylemods=default

(26)

2. Package Options

Patches all the predefined styles that have been loaded, without loading any extra styles. This will typically be all the styles that are usually loaded byglossaries(for example,listandlong).

Package options such asnolistwill alter which styles are loaded. In the case ofnostyles, no styles will be loaded, so none of them will be patched.

� It’s pointless using both stylemods=default and nostyles. Any glossary style packages that are subsequently loaded won’t be patched.

� stylemods=hlisti

For each elementhtagi inhlisti, the corresponding package glossary-htagi will be loaded.

You can use this in combination withnostylesto only load the particular style package or packages that you require (without loading the full set of defaults). For example,

�

\usepackage[nostyles,stylemods={bookindex,longextra}, style=bookindex]{glossaries-extra}

This prevents the base glossaries package from loading the default set of styles, but loads glossaries-extra-stylemods,glossary-bookindexandglossary-longextra, and then sets the default style tobookindex.

2.3. Loading Other Packages

Some options listed in other sections, such as thestylemodsandrecordoptions, also load supplementary packages.

� prefix

Loads theglossaries-prefixpackage (if not already loaded).

accsupp �

Loads theglossaries-accsupppackage (if not already loaded). This option can only be used as a package option (not in \glossariesextrasetup) as glossaries-extra needs to know whether or not to provide accessibility support while it’s loading.

(27)

2. Package Options

� Theglossaries-accsupppackage is still experimental and so accessibility features are liable to change.

If you want to define styles that can interface with the accessibility support provided by glossaries-accsuppuse the\glsaccesshxxxitype of commands instead of\glsentryhxxxi (for example, \glsaccesstext instead of \glsentrytext). If glossaries-accsupp hasn’t been loaded those commands are equivalent (for example,\glsaccesstextjust does\glsentrytext) but if it has been loaded, then the\glsaccesshxxxi commands will add the accessibility information. See §9 for further details.

2.4. Entry Definitions, References and Indexing

�

undefaction=hvaluei initial: error

This indicates what to do if an undefined glossary entry is referenced.

� Undefined entries can’t be picked up by any commands that iterate over a glossary list. This includes\forglsentriesand\glsaddall.

� undefaction=error

Produces an error message for undefined glossary entries.

� undefaction=warn

Only produces a warning message for undefined glossary entries. The place where the entry has been referenced will be marked with ?? (as with undefined labels or citations). The unknown marker is produced with:

�

\glsxtrundeftag initial: ??

This defaults to two question marks.

Note that\ifglsusedwill only display?? in the document text withundefaction=warn if the entry hasn’t been defined, as the underlying boolean variable doesn’t exist and so is neither true nor false. (There will also be a warning in the transcript.) You may prefer to use

\GlsXtrIfUnusedOrUndefinedinstead. See §5.10 for further details.

(28)

2. Package Options

If you want to write a custom command that needs to generate a warning or error for an undefined reference, you can use:

�

\glsxtrundefaction{hmessagei}{hadditional helpi}

This will produce the unknown marker if used within the document environment. Depend- ing on theundefaction, \glsxtrundefactionwill either create an error with the given hmessageiandhadditional helpior will create a warning with the givenhmessagei.

� docdef=hvaluei default: true;initial: false This setting governs where\newglossaryentrycan be used (preamble-only or anywhere before the first glossary or anywhere within the document).

Commands like \newabbreviation and \glsxtrnewsymbol that internally use \newglossaryentry are also governed by this option. Other commands, such as \longnew- glossaryentryare always preamble-only.

With just the base glossariespackage, \newglossaryentry is allowed in the document environment as long as you haven’t used \makenoidxglossaries. There are, however, problems that can occur when entries are defined within thedocumentenvironment (see the glossariesdocumentation for further details). To encourage preamble-only use, theglossaries -extrapackage prohibits the use of\newglossaryentrywithin thedocumentenvironment by default, but if you really want this you can use this package option to allow it.

� Note that in the case ofbib2gls, all entry data is originally defined inbibfiles. The entry definitions (using commands like \longnewglossaryentry and \newabbreviation) are written to theglstexfiles that are input in the preamble.

� docdef=false

Prohibits the use of \newglossaryentry within the document environment. All entries must be defined in the preamble.

� docdef=true

Permits the use of \newglossaryentry in the document environment provided \make- noidxglossarieshasn’t been used (as per the base glossaries package). This will create a temporary glsdefsfile that contains the entry definitions so that they can be available on the next L^ATEX run at the beginning of the document to allow any glossaries in the front

(29)

2. Package Options

If all your glossaries occur at the end of the document, consider usingdocdef=restricted instead.

� docdef=restricted

Permits the use of \newglossaryentryin the documentenvironment provided the entry definitions all occur before the first glossary is displayed.

This avoids the need for theglsdefsfile. You will still need to take care about any changes made to the category code of characters that are required by thehkeyi=hvalueimechanism (that is, the comma and equal sign) and any makeindex or xindy special character that occurs in thesortkey or label. If any of those characters are made active in the document (for example, throughbabelshortcuts), then it can cause problems with the entry definition.

This option will allow\newglossaryentryto be used in the document with\makenoidxglossaries, but note that\longnewglossaryentryremains a preamble-only command.

With this option, if an entry appears in the glossary before it has been defined, an error will occur (or a warning if theundefaction=warnoption is used). If you edit your document and either remove an entry or change its label, you may need to delete the document’s temporary files (such as theauxandglsfiles).

� docdef=atom

This option behaves likedocdef=restrictedbut creates theglsdefsfile for atom’s autocomplete support. This file isn’t input byglossaries-extraand so associated problems with the use of this file are avoided, but it allows the autocomplete support to find the labels in the file.

� A bug fix inglossariesv4.47 has changed the format of theglsdefsfile slightly.

As withdocdef=restricted, entries may be defined in the preamble or anywhere in the document, but they may only be referenced after they have been defined. Entries must be defined before the associated glossary is displayed.

If you need a list of all entry labels for the use of an editor or helper script you may also want to consider the package optionswriteglslabelsandwriteglslabelnamesprovided by the base glossariespackage. Note that with these options and withdocdef=atom, only the entry labels that are visible to L^ATEX can be saved. So if you are using bib2glsyou will only get the labels of the entries that have already been selected bybib2gls. Thebibfiles can be found by parsing the aux file for \glsxtr@resource (listed in the src option or

\jobname.bibifsrcis missing).

�

shortcuts={hvaluei} initial: none

(30)

2. Package Options

Unlike the baseglossariespackage option of the same name, this option isn’t boolean but has multiple values.

� Multiple invocations of theshortcutsoptionwithin the same option listwill override each other. Since these options define commands, the action can’t be undone with a later\glossariesextrasetup.

� shortcuts=ac

Set the shortcut commands provided by the base glossariespackage for acronyms (such as

\ac) but use theglossaries-extraabbreviation commands, such as\glsxtrshortand\gls- xtrlong, instead of the analogous base commands, such as\acrshortand\acrlong. See

§4.3.2 for further details.

� shortcuts=abbreviations

Sets the abbreviation shortcuts (see §4.3.2). This setting doesn’t switch on the acronym shortcuts provided by the baseglossariespackage.

�

shortcuts=abbr alias: abbreviations

Synonym forshortcuts=abbreviations.

� shortcuts=other

Implements the other (non-abbreviation) shortcut commands:

�

\newentry{hentry-labeli}{hoptionsi} A synonym for\newglossaryentry.

�

\newsym[hkey=value listi]{hentry-labeli}{hsymi}

A synonym for\glsxtrnewsymbol(provided that thesymbolspackage option is also used).

(31)

2. Package Options

�

\newnum[hkey=value listi]{hentry-labeli}{hnumi}

A synonym for\glsxtrnewnumber(provided that thenumberspackage option is also used).

� shortcuts=acother

Implementsshortcuts=acandshortcuts=other.

� shortcuts=abother

Implementsshortcuts=abbreviationsandshortcuts=other.

� shortcuts=all

Implementsshortcuts=ac,shortcuts=abbreviationsandshortcuts=other.

� shortcuts=acronyms

Sets the shortcuts provided by the baseglossariespackage for acronyms (such as\ac). See theglossariespackage documentation for further details.

Note that the short and long forms (\acsand\acl) don’t use\glsxtrshortand\gls- xtrlongbut use the original\acrshort and\acrlong, which aren’t compatible with the glossaries-extraabbreviation mechanism. The better option is to useshortcuts=ac.

� Don’t useshortcuts=acronymsunless you have reverted\newacronymback to the baseglossariespackage’s acronym mechanism. See §4.6 for further details.

�

shortcuts=acro alias: acronyms

Synonym forshortcuts=acronyms.

�

shortcuts=true alias: all

This setting is provided by the baseglossariespackage. Withglossaries-extrait’s equivalent

(32)

2. Package Options

toshortcuts=all.

�

shortcuts=false alias: all

This setting is provided by the baseglossariespackage. Withglossaries-extrait’s equivalent toshortcuts=none.

� indexcrossrefs=hbooleani default: true;initial: varies This is a boolean option that governs whether or not to automatically index any cross- referenced entries that haven’t been marked as used at the end of the document. These are entries that are identified in one of the cross-referencing fields (seeandseealso) of another used entry as opposed to entries that have the cross-referencing fields set.

Since entries with thealiaskey are intended as synonyms for another term, the target is expected to be indexed so entries with thealiaskey set aren’t affected by this option.

For example:

�

\newglossaryentry{courgette}{name={courgette}, description={small vegetable marrow}}

\newglossaryentry{marrow}{name={marrow}, description={long gourd with green skin}, seealso={courgette}}

Suppose that “marrow” is indexed (so that it appears in the glossary with the cross-reference to “courgette”) but if courgette isn’t indexed anywhere in the document (using commands like\glsor\glsadd) then there will be a broken cross-reference in the marrow location list pointing to courgette, which doesn’t appear in the glossary. Withindexcrossrefs=true, the courgette entry will be indexed at the end of the document using\glsaddwithformat

=glsxtrunusedformat, which corresponds to the command\glsxtrunusedformat.

Note that this special format\glsxtrunusedformat simply does \unskipand ignores its argument, which creates a blank location. If any of the cross-referenced entries have been indexed but haven’t been marked as used (for example, with\glsadd) then this will cause a spurious comma in the location list. This is a limitation of the way thatmakeindex andxindywork as they are general purpose indexing applications which require locations.

If you have entries with cross-references, you may want to consider switching tobib2gls instead.

� Note thatbib2glscan automatically find dependent entries when it parses thebib source file, so therecordoption automatically implementsindexcrossrefs=false.

(33)

2. Package Options

This function is implemented by code added to the end document hook that determines whether or not to use the command\glsxtraddallcrossrefs. This command iterates over all entries in all glossaries, which adds to the overall document build time, especially if you have defined a large number of entries, so this defaults toindexcrossrefs=false, but it will be automatically switched on if you use the seeorseealsokeys in any entries. See also §5.9.

� indexcrossrefs=true

Enables this setting.

� indexcrossrefs=false

Disables this setting even if theseeorseealsokey is present in any entries.

� autoseeindex=hbooleani default: true;initial: true This is a boolean option that governs whether or not the see and seealso keys should automatically index the cross-reference when an entry is defined (see §5.9).

With the baseglossariespackage, theseekey was provided as a shortcut for\glssee. For example:

�

\newglossaryentry{zucchini}{name={zucchini}, description={},

see={courgette}}

is equivalent to:

�

\newglossaryentry{zucchini}{name={zucchini}, description={}}

\glssee{zucchini}{courgette}

This was designed for documents where only entries that are actually used in the document are defined and ensures that the cross-reference is included in the glossary, even though it may not be referenced anywhere in the document. However, it becomes problematic if neither entry is required in the document.

(34)

2. Package Options

Theglossaries-extrapackage modifies the action of theseekey so that it also saves the value and will only perform the automated\glsseeif autoseeindex=true. Similarly for theseealsokey.

� Note that therecordoption automatically implementsautoseeindex=falseas the corresponding action can be implemented withbib2gls’sselectionoption.

� autoseeindex=true

Enables automatic indexing using\glsseefor theseekey (as per the baseglossariespackage) and\glsxtrindexseealsofor theseealsokey.

For example, if an entry is defined as

�

\newglossaryentry{foo}{name={foo}, description={},see={bar,baz}}

then, withautoseeindex=trueand the defaultindexcrossrefssetting, this is equivalent to

�

\newglossaryentry{foo}{name={foo},description={}}

\glssee{foo}{bar,baz}

\glossariesextrasetup{indexcrossrefs=true}

\GlsXtrSetField{foo}{see}{bar,baz}

� autoseeindex=false

The value of theseeandseealsokeys will be stored in their corresponding fields (and can be accessed using commands like\glsxtruseseeand\glsxtruseseealso) but the cross- reference won’t be automatically indexed.

� Note that indexcrossrefs isn’t automatically implemented by the presence of the seekey whenautoseeindexis false.

For example, if an entry is defined as

(35)

2. Package Options

�

\newglossaryentry{foo}{name={foo}, description={},see={bar,baz}}

then, withautoseeindex=falseand the defaultindexcrossrefssetting, this is equivalent to

�

\newglossaryentry{foo}{name={foo}, description={}}

\GlsXtrSetField{foo}{see}{bar,baz}

It’s therefore possible with this option to remove the cross-references from the location lists and set their position within the glossary style.

Another method of preventing the automatic indexing is to define the entries before the external indexing files have been opened with\makeglossaries. Since the appropriate file isn’t open, the information can’t be written to it. This will need the package optionseeno- index=ignoreto prevent an error occurring.

� record=hvaluei default: only;initial: off This setting indicates whether or notbib2glsis required.

� This option can only be set in the preamble and can’t be used after \GlsXtrLoad- Resourcesor\glsxtrresourcefile.

With the recording setting on (record=only,record=namereforrecord=hybrid), any of the commands that would typically index the entry (such as\gls,\glstextor\glsadd) will add a record to theauxfile. bib2glscan then read this information to find out which entries have been used. (Remember that commands like\glsentrynamedon’t index, so any use of these commands won’t add a corresponding record.) See §11 for further details.

The hybrid method additionally performs the standard indexing action that’s required for makeindexorxindyto work, but this can’t be done untilbib2glshas created theglstex files that provide the entry definitions. In general, it’s best to avoid the hybrid method.

� record=off

Indexing is performed as per the baseglossariespackage using either\makeglossariesor

(36)

2. Package Options

\makenoidxglossaries. This setting implementsundefaction=error.

� record=only

Indexing (or recording) is performed by adding bib2gls records in the aux file. Neither

\makeglossariesnor\makenoidxglossariesis permitted. Use\GlsXtrLoadResources (or\glsxtrresourcefile) to set up bib2glsresource options. Glossaries should be displayed with the “unsrt” family of commands, such as\printunsrtglossary.

This setting implementsundefaction=warn,autoseeindex=false,indexcrossrefs=

falsesort=none, and automatically loads the supplementaryglossaries-extra-bib2glspack- age. (There should be no need to explicitly loadglossaries-extra-bib2gls.)

This option also defines thelocationandgroupkeys that are set bybib2glsto provide the location list and group information required by the “unsrt” family of commands.

The document build process is (assuming the file is calledmyDoc.tex):

� pdflatex myDoc

bib2gls myDoc pdflatex myDoc

If you want letter groups you will need the--groupor-gswitch when invokingbib2gls:

� pdflatex myDoc

bib2gls -g myDoc pdflatex myDoc

� Note that this setting will prevent theseefrom automatically implementing\glssee. (bib2glsdeals with theseefield.) You may explicitly use\glsseein the document, but bib2glswill ignore the cross-reference if thesee field was already set for that entry.

� record=nameref

Asrecord=onlybut uses nameref records, which include the current label information given by\@currentlabeland\@currentHref. This means that the title can be included in the entry locations, if available. This setting also supports location hypertargets that don’t follow a simplehh-prefixihthe-counteriformat, which can’t be used with other indexing options.

See §11.5.6 for further details of this option.

(37)

2. Package Options

� This option requireshyperref, otherwise it will fall back on the usual location records.

Note that \@currentHref is always globally updated whenever \refstepcounter is used, but\@currentlabelisn’t. This can cause some undesired side-effects with some settings. Remember also that theindexcounteroption increments the associated counter every time an entry is indexed, which affects this option. If the location counter is the default page, only the location number is shown.

�

record=alsoindex alias: hybrid�

Deprecated synonym ofrecord=hybrid.

� record=hybrid

This is a hybrid setting that usesbib2glsto fetch entry information frombibfiles, but uses makeindexor xindyto create the glossary files (which are input with \printglossary).

Note that this requires a slower and more complicated build process (see below).

This hybrid approach is provided for the rare instances where an existingxindyrule or module is too complicated to convert to abib2glsrule but the entries need to be fetched from abibfile. There’s no benefit in using this option withmakeindex.

This setting does not loadglossaries-extra-bib2gls, asbib2glsis only being used to fetch the entry definitions.

� Since it’s redundant to make bib2gls also sort and collate locations (in addition to xindy performing these tasks), use the resource options sort=none and save -locations=false for a faster build. Many of the other resource options are likely to be irrelevant.

This setting must be used with \makeglossaries but not with its optional argument.

Each glossary should be displayed using\printglossary(or\printglossariesfor all of them).

� This setting should not be used with\makenoidxglossaries.

You may need to change the transcript file used bybib2glsto avoid a clash withxindy’s transcript file. This can be done withbib2gls’s--log-fileor-toption.

The document build process is (assuming the file is calledmyDoc.tex):

(38)

2. Package Options

� pdflatex myDoc

bib2gls myDoc pdflatex myDoc

makeglossaries myDoc pdflatex myDoc

Note that, in this case, it’s redundant to callbib2glswith the--groupor-gswitch asxindy will insert the group heading information into the corresponding glossary file.

� If you wantbib2glsto form the letter groups then this hybrid method is inappropri- ate.

�

bibglsaux=hbasenamei initial: empty

requiresbib2glsv3.0+

Alternatively, this setting can be implemented with:

�

\glsxtrsetbibglsaux{hbasenamei}

This option should only be used once. If used again no new file will be created. If the hbasenameivalue is empty, records will be written to the normalauxfile.

A document containing many records can result in a largeauxfile with information that’s only relevant tobib2gls. This option will create a new file calledhbasenamei.auxthat will be used to store the records. The file will be skipped by L^ATEX but will be picked up bybib2gls v3.0+ when it inputs the mainauxfile. Note that this creates an extra write register.

� You should still supply the mainauxfile when you runbib2glsashbasenamei.aux will only contain the records and not the other information that bib2gls requires (such as the resource options).

� equations=hbooleani default: true;initial: false This setting will cause the default location counter to automatically switch toequationwhen inside a numbered equation environment, such as equation or align. The counter can be

(39)

2. Package Options

explicitly overridden with thecounter\glslinkoption.

� floats=hbooleani default: true;initial: false This setting will cause the default location counter to automatically switch to the corresponding counter when inside a floating environment, such asfigureortable. The counter can be explicitly overridden with thecounter\glslinkoption.

Remember that within floats it’s the \caption command that actually uses\refstepcounter, so indexing before the caption will result in the wrong reference. The commands for use in captions and sections, such as\glsfmttextand\glsfmtshort, don’t index. (See

§5.3). You may want to consider using\glsaddafter the caption (not before). For example:

�

\begin{figure}[htbp]

\centering

\includegraphics{example-image}

\caption{Sample \glsfmttext{foobar} figure}

\glsadd{foobar}

\end{figure}

� indexcounter

This option defines the indexing counter:

wrglossary №

which is incremented every time an entry is indexed. This option automatically implements counter=wrglossary. This means that each location will link to the relevant part of the page where the indexing occurred (instead of to the top of the page). See thebib2glsdoc- umentation for thesave-index-counterresource option for more details.

� This option is primarily intended for use withbib2gls(v1.4+) andhyperref. It can be used withmakeindexorxindy, but it will interfere with the location list collation, so you won’t have ranges and you’ll have duplicate page numbers present.

This option works by incrementingwrglossarywith\refstepcounterand adding\label. This can cause a problem if the indexing occurs in anequationenvironment asamsmathfor- bids multiple occurrences of\label(resulting in the “Multiple\label’s” error). It’s best to change the counter topageorequationwhen in maths mode with this option. For example:

(40)

2. Package Options

�

\renewcommand{\glslinkpresetkeys}{%

\ifmmode \setupglslink{counter=page}\fi}

\renewcommand{\glsaddpresetkeys}{%

\ifmmode \setupglsadd{counter=page}\fi}

2.5. Debugging

� debug=hvaluei default: true;initial: false Enables debugging information for draft documents. This option is defined by the base glossariespackage, but is extended by glossaries-extrato provide additional settings. If no value is provided,trueis assumed. The following values are available:

� debug=false

This setting is provided by the glossariespackage and is the default. This switches off all debugging commands.

� debug=true

This setting is provided by theglossariespackage and switches on logging information if an entry is indexed before the relevant indexing files have been opened (only applicable with makeindexandxindy). This option is extended byglossaries-extrato also display the label of unknown entries before the?? marker.

� �

\usepackage[debug]

{glossaries-extra}

\begin{document}

\gls{example}

\end{document}

[example]⁇

This uses\glsshowtargetfonttextfor the annotation, which is provided byglossaries.

� debug=showaccsupp

(41)

2. Package Options

Provided byglossaries, this setting shows accessibility information (glossaries-accsupp).

� debug=all

Implements all debugging options.

� debug=showwrgloss

This setting is only available withglossaries-extra. This implementsdebug=trueand shows a marker (·) just before the write operation is performed by indexing commands. Withrecord

=hybridthere will be two marks: one for the write operation to the auxfile and one for the associated glossary file used by makeindex/xindy. The marker is produced with the command:

�

\glsxtrwrglossmark

If theindexcounteroption has been used, this setting will also mark where thewrglossary counter has been incremented. The marker is produced with the command:

�

\glsxtrwrglosscountermark{hnumberi}

This marker is also inserted before the location in the definition of\glsxtrwrglossaryloc- fmt.

� debug=showtargets

This setting is provided by glossaries and displays the hyperlink target names whenever any glossary-related commands create a hyperlink or hypertarget (for example,\gls,\gls- targetor\glshypernumber). The default is to use marginal notes in TEX’s “outer” mode and inline annotations for “inner” or maths modes. This uses \glsshowtargetinner for inner and maths annotations and\glsshowtargetouterfor the outer annotation.

If there are many targets within a single paragraph this can lead to “too many floats”, so glossaries-extraprovides a new package option showtargets that can be used to eas- ily switch to inline annotations for outer mode (rather than having to redefine\glsshow- targetouter).

� showtargets=hvaluei

(42)

2. Package Options

Automatically implements debug=showtargets and adjusts the annotations according to thehvaluei. Theglossaries-extrapackage provides supplementary commands to support this option.

�

\glsxtrshowtargetouter{htarget-namei}

Formats annotations in outer mode. This is initially\glsshowtargetouterto matchdebug

=showtargets.

�

\glsxtrshowtargetinner{htarget-namei}

Formats annotations in inner mode. This is initially\glsshowtargetinnerto matchdebug

=showtargets.

�

\glsshowtargetinnersymleft{name}

Shows the left annotation and marker. This uses the left symbol marker:

�

\glsxtrshowtargetsymbolleft

�

\glsshowtargetinnersymright{name}

Shows the right marker and annotation. This uses the right symbol marker:

�

\glsxtrshowtargetsymbolright

� showtargets=left

A marker is placed to the left of the link/target and a marginal note is used in outer mode.

� showtargets=right

(43)

2. Package Options

A marker is placed to the right of the link/target and a marginal note is used in outer mode.

� showtargets=innerleft

A marker and annotation are placed to the left of the link/target in all modes.

� showtargets=innerright

A marker and annotation are placed to the right of the link/target in all modes.

� showtargets=annoteleft

Markers are placed on either side of the link/target with the annotation on the left in all modes.

� showtargets=annoteright

Markers are placed on either side of the link/target with the annotation on the right in all modes.

(44)

3. Defining Entries

The baseglossariespackage provides commands, such as\newglossaryentry, to define entries. Theglossaries-extrapackage provides some additional commands, described in §3.1.

For abbreviations, see §4. If you usebib2gls, it will write command definitions within the glstexfile. See thebib2glsuser manual for further information about those commands.

Theglossariesuser manual warns against using commands such as\glswithin field values. However, if you really need this, theglossaries-extrapackage provides\glsxtrp(see

§5.4). Alternatively, you may want to consider multi (compound) entries instead (see §7).

3.1. Command Definitions

�

\longnewglossaryentry{hentry-labeli}{hkey=value listi}{hdescriptioni}

This command is provided by the baseglossariespackage to cater for entries with descrip- tions that contain paragraph breaks. (Thehkeyi=hvalueiinterface doesn’t support paragraph breaks in the value.) The base package only provides an unstarred version of this command, which automatically inserts\leavevmode\unskip\nopostdescat the end of the description. Theglossaries-extrapackage replaces this with a single command:

�

\glsxtrpostlongdescription

which has the same effect, but can be redefined if required.

Theglossaries-extrapackage provides a starred form:

�

\longnewglossaryentry*{hentry-labeli}{hkey=value listi}{hdescriptioni} This doesn’t insert the hook at the end of the description.

� For a general purpose post-description hook, see §8.6.2.

Additionally, thesymbolspackage option provides\glsxtrnewsymbol, and thenumbers package option provides\glsxtrnewnumber. See §2.1 for further details.

(45)

3. Defining Entries

3.2. Glossary Entry Keys

In addition to the glossary entry keys provided by the baseglossariespackage (summarised in §II) theglossaries-extrapackage provides:

� category=hcategory-labeli initial: general Assigns the category label. This should not contain any special or active characters as it’s used to form command names. See §10 for further details.

� seealso={hxr-listi}

This key is analogous to thesee key but the tag is always given by \seealsoname. The valuehxr-listishould be a comma-separated list of entry labels. As with theseekey, this key automatically indexes the cross-reference by default. The cross-reference will be displayed in the location list using\glsxtruseseealsoformat(see §5.9). Useautoseeindex=false to prevent the automatic indexing. (Withbib2gls, adjust theselectioncriteria.)

� With just the base glossaries package, the see key simply performs this automated indexing. With glossaries-extrathe value is also saved. Similarly with theseealso key. The value isn’t saved with explicit use of\glsxtrindexseealsoor\glssee.

� alias={hxr-labeli}

This is similar to the see key but the value can only be a single entry label. In addition to automatically indexing the cross-reference, this command will cause the entry with this key to have hyperlinks go to the aliased entry when referenced with commands like\gls. Whenever the entry is indexed with commands like\gls, the indexing will be performed on the target entry (thealiasvalue). See §5.9 for further details.

� Any entry that has a see, seealsoor alias key set will be added to the glossary by default when using makeindex orxindy. If you don’t want this behaviour, use theautoseeindex=falsepackage option and implement a post-description hook to insert the cross-reference. Alternatively, consider switching tobib2gls.

If you usebib2gls(see §11) then most of the glossary entry keys can be used as analogous fields in thebibfile. For example, instead of writing the following code in yourtexfile:

Index of /CTAN/macros/latex/contrib/glossaries-extra

glossaries-extra.sty v1.49: an extension to the glossaries package

Nicola L.C. Talbot Dickimaw Books dickimaw-books.com

2022-10-14

Contents

I. User Guide 1

II. Summaries and Index 597

List of Examples

Part I.

User Guide

1. Introduction

1.1. Package Defaults

1.2. Example Differences Between glossaries and glossaries-extra

1.2.1. Basic defaults

1.2.2. Language defaults

1.2.3. Combined with memoir

1.2.4. Abbreviations

1.2.5. Glossary Mid-Build Placeholder (\printglossary)

1.3. Further Reading

2. Package Options

2.1. Glossary Lists

2.2. Glossary Style Options

2.3. Loading Other Packages

2.4. Entry Definitions, References and Indexing

2.5. Debugging

3. Defining Entries

3.1. Command Definitions

3.2. Glossary Entry Keys