From a0a43165d11c155e15abb9051332c8b4e5576db6 Mon Sep 17 00:00:00 2001
From: Karl Berry
glossaries-extra.sty v1.45: an extension to the
+class="cmr-17">glossaries-extra.sty v1.46: an extension to the
glossaries package
2020-04-01http://www.dickimaw-books.com/
-
Abstract
The glossaries-extra package is an extension to the glossaries package, providing @@ -278,12 +280,20 @@ class="cmtt-10">.bib files for use with id="dx1-2">bib2gls. +
The glossaries-extra package uses a different set of defaults to the base +glossaries package. See the Introduction for more details. +
-
Additional resources:
++
Additional resources:
The glossaries-extra documented code glossaries-extra-code.pdf. -
The glossaries-extra gallery. -
glossaries-extra and bib2gls: An Introductory Guide. (bib2gls-begin.pdf). -
Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build. -
The bib2gls application. -
The base glossaries package.
The The glossaries package 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).
- The The glossaries-extra package is an attempt to provide a compromise for this
conflict. Version 4.22 of the glossaries package is the last version to incorporate new
@@ -503,10 +519,10 @@ 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.
I’m not happy with some of the default settings assumed by the I’m not happy with some of the default settings assumed by the glossaries package,
and, judging 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
@@ -516,9 +532,10 @@ but since glossaries-extra is 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: The new defaults are: nopostdot=truepostdot to restore the
terminating full stop (period).
- noredefwarn=true=false If babel has been loaded, the =truebabel hasn’t been loaded.
+ The default style used by \newacronym is short-nolong. (That is, the long
+ form is not shown on first use.)
+ The examples below illustrate the difference in explicit package options between
+ The examples below illustrate the difference in explicit package options between
glossaries and glossaries-extra. There may be other differences resulting from
modifications to commands provided by glossaries (see §2 Modifications to Existing
-Commands and Styles).
-
+class="tcrm-1000">§??sec:modifications
+1.1 Package Defaults
-
Basic defaults: -
\documentclass{article} -
\usepackage{glossaries-extra} -
This is like: + \usepackage{glossaries-extra} + +
This is like:
-\documentclass{article} -
\usepackage[toc,nopostdot]{glossaries} -
\usepackage{glossaries-extra} -
+ \usepackage[toc,nopostdot]{glossaries} + \usepackage{glossaries-extra} + +
Language defaults: -
\documentclass[british]{article} -
\usepackage{babel} -
\usepackage{glossaries-extra} -
This is like: + \usepackage{babel} + \usepackage{glossaries-extra} + +
This is like:
-\documentclass[british]{article} -
\usepackage{babel} -
\usepackage[toc,nopostdot,translate=babel]{glossaries} -
\usepackage{glossaries-extra} -
+ \usepackage{babel} + \usepackage[toc,nopostdot,translate=babel]{glossaries} + \usepackage{glossaries-extra} + +
\documentclass{memoir} -
\usepackage{glossaries-extra} -
This is like: + \usepackage{glossaries-extra} + +
This is like:
-\documentclass{memoir} -
\usepackage[toc,nopostdot,noredefwarn]{glossaries} -
\usepackage{glossaries-extra} -
+ However
This is like:
+ \usepackage{glossaries}
+ \usepackage{glossaries-extra}
+
+ This is like:
Since by the time
+ Since by the time glossaries-extra has been loaded, glossaries has already
redefined memoir’s glossary-related commands.
\documentclass{memoir}
-
\usepackage{glossaries}
-
\usepackage{glossaries-extra}
-
\documentclass{memoir}
-
\usepackage[toc,nopostdot]{glossaries}
-
\usepackage{glossaries-extra}
-
Another noticeable change is that by default ’s glossary-related commands. +
+Abbreviations are defined with \newabbreviation: + + + +
++ \usepackage{glossaries-extra} + \newabbreviation{svm}{SVM}{support vector machine} + \begin{document} + First use: \gls{svm}. Explicit full form: \glsxtrfull{svm}. + \end{document} ++
This is the closest 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 \newacronym then you will need to change the + style for the acronym category: + + + +
++ \usepackage{glossaries-extra} + \setabbreviationstyle[acronym]{long-short} + \newacronym{svm}{SVM}{support vector machine} + \begin{document} + First use: \gls{svm}. Explicit full form: \glsxtrfull{svm}. + \end{document} ++
Another noticeable change is that by default \printglossary will 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 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 +
This change is mostly likely to be noticed by users with one or more redundant empty glossaries who ignore transcript messages, explicitly use makeindex/xindy on just the non-empty glossary (or glossaries) and use the iterative \printglossaries command instead of command instead of \printglossary. For example, consider the + id="dx1-3032">. For example, consider the following:
-\documentclass{article} -
\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 +\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 \printglossaries occurs. However it will also attempt to input the occurs. However it will also attempt to input the .gls file associated with the main glossary. -
If you use If you use makeglossaries, you’ll get the warning message:
(where the original file is called
+ (where the original file is called test.tex) but if you simply call makeindex directly
to generate the
- This doesn’t occur with
+ This doesn’t occur with makeglossaries as it will create the .gls file containing
the single command \null.
- If you simply change from If you simply change from glossaries to glossaries-extra in this document, you’ll
find a change in the resulting PDF if you don’t use The transcript file will still contain the message about the missing The transcript file will still contain the message about the missing .gls, 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 the
nomain package option:
+ id="dx1-3039">
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.
-
No file test.gls.
-
\documentclass{article} -
\usepackage[nomain,acronym,postdot]{glossaries-extra} -
\makeglossaries -
\setabbreviationstyle[acronym]{long-short} -
\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 \setabbreviationstyle before
-
+ (Note the need to set the acronym style using \setabbreviationstyle
+before \newacronym. See §4 Abbreviations for further details.)
-
+class="tcrm-1000">§
-
If you haven’t already loaded If you haven’t already loaded glossaries, you can use any of the package options
provided by glossaries when you load \setupglossariesglossaries
-
The new and modified options provided by
+ The new and modified options provided by glossaries-extra are described
below:
The glossaries package has a debug option that allows the values false, @@ -865,7 +956,7 @@ class="cmss-10">glossaries
The The glossaries-extra package extends this option to provide the additional
values debug=all.
- The The debug=showwrglossdebug=true and uses
-
+
to show a mark ⋅ just before the write operation performed by the
indexing commands. If you use record=alsoindex=hybrid there will be a mark
for the write operation to the .aux file for makeindex or
id="dx1-4012"> The The debug=alldebug=showwrgloss.
(New to version 1.12.) This option is just a shortcut for nopostdot=false.
- (New to version 1.21.) This option sets the post-description punctuation to the
+ given value. For example: postpunc=; does
- The value may also be one of the following keywords:
+
+ The value may also be one of the following keywords:
comma:
+
+
dot:
-
\renewcommand{\glspostdescription}{;}
-
\renewcommand{\glspostdescription}{,}
-
\renewcommand{\glspostdescription}{.\spacefactor\sfcode`\. } -
+ +
none:
\renewcommand{\glspostdescription}{} -
The default definition is + +
+The default definition is
-\newcommand*{\glspostdescription}{% -
\ifglsnopostdot\else.\spacefactor\sfcode`\. \fi -
} -
where the conditional is determined by the
+ where the conditional is determined by the nopostdot package option.
@@ -1024,7 +1129,7 @@ class="cmss-10">postdot
The The glossaries-extra-stylemods package adjusts the predefined styles
that had a hard-coded \hfil:
Be careful with doing this as it will look odd if the
+ Be careful with doing this as it will look odd if the number list is missing.
(With loc-prefix
\usepackage[postpunc=comma,stylemods]{glossaries-extra}
-
\renewcommand{\glsxtrprelocation}{\hfil}
-
Load the glossaries-prefix package (if not already loaded). -
Load the glossaries-accsupp package (if not already loaded). -
-
If you want to define styles that can interface with the accessibility support +
+
If you want to define styles that can interface with the accessibility support provided by glossaries-accsupp use the \glsaccesstext just does \glsentrytext) but if it has been loaded, then the \glsaccess⟨xxx⟩ commands will add the - accessibility information. (See xxx
⟩ commands will add the accessibility + information. (See §12.2 §??sec:accsupp Accessibility Support for further details.) -Note that the Note that the accsupp option can only be used as a package option (and can’t
@@ -1122,23 +1232,29 @@ class="cmss-10">glossaries-accsuppglossaries-extra if it’s required.
This is a ⟨key⟩=⟨value⟩ option used to load the glossaries-extra-stylemods - package. The value may be a comma-separated list of options to pass to that - package. (Remember to group ⟨value⟩ if it contains any commas.) The value may - be omitted if no options need to be passed. See package. + The value may be a comma-separated list of options to pass to that package. + (Remember to group ⟨value⟩ if it contains any commas.) The value may be + omitted if no options need to be passed. See §2.10.1 Glossary Style - Modifications for further details. There are two special keyword values: +class="tcrm-1000">§??sec:glosstylemods Glossary + Style Modifications for further details. There are two special keyword values: stylemodsstylemods=all, which loads all the predefined styles. -
This is a ⟨key⟩=⟨value⟩ option, which has two allowed values: warn and - - - - error. This indicates what to do if an undefined glossary entry is referenced. The - default behaviour is warn
-
Note that
+ Note that \ifglsused will display ?? in the document text with
- will display ?? in the document text with undefaction=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.) See
+ 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.) See §2.6 §
This is a boolean option. If true, this will automatically index any cross-referenced entries that haven’t been marked as used at the end of the document. Note that this necessarily adds to the overall document build time, @@ -1228,7 +1346,7 @@ class="cmss-10">indexcrossrefs
Note that Note that bib2gls can automatically find dependent entries when it
@@ -1243,23 +1361,28 @@ class="cmss-10">indexcrossrefs
(New to v1.16.) This is a boolean option. If true (default), this makes the see and
+ and seealso keys automatically index the cross-reference when an entry
- is defined. If false, the value of those keys will still be stored in their
+ id="dx1-4068"> keys automatically index the cross-reference when an entry is
+ defined. If false, the value of those keys will still be stored in their
corresponding fields (and can be accessed using commands like \glsxtrusesee
and \glsxtruseseealso) but cross-reference won’t be automatically
indexed.
- Note that the Note that the record=onlyautoseeindex=false.
- For example, if an entry is defined as
+ For example, if an entry is defined as
then with
+ then with autoseeindex=true, this is equivalent to
but with
+ but with autoseeindex=false, this is equivalent to
Note that
+ Note that indexcrossrefs isn’t automatically implemented by the presence of the
@@ -1308,9 +1431,9 @@ class="cmss-10">see It’s therefore possible to remove the cross-references from the location lists and
+ It’s therefore possible 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
+ 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.
@@ -1319,33 +1442,50 @@ class="cmss-10">seenoindex=ignore
\newglossaryentry{foo}{name={foo},description={},see={bar,baz}}
-
\newglossaryentry{foo}{name={foo},description={}}
-
\glssee{foo}{bar,baz}
-
\glossariesextrasetup{indexcrossrefs=true}
-
\GlsXtrSetField{foo}{see}{bar,baz}
-
\newglossaryentry{foo}{name={foo},description={}}
-
\GlsXtrSetField{foo}{see}{bar,baz}
-
(New to v1.08.) This is a ⟨key⟩=⟨value⟩ option provided for the benefit of - value
The option may only be set in the preamble and can’t be used after +class="cmtt-10">bib2gls: Managing Reference Databases). If you want to + use bib2gls, the recommended setting is record=nameref if you have hyperlinks + and record=only if you don’t have hyperlinks. +
The option may only be set in the preamble and can’t be used after \GlsXtrLoadResources. If the value is missing record=only is assumed. + id="dx1-4079"> is assumed. Permitted values:
off
This is the default setting. The indexing is performed as normal using either \makeglossaries or \makenoidxglossaries. This setting @@ -1353,94 +1493,118 @@ class="cmtt-10">\makenoidxglossaries. This setting href="#styopt.undefaction">undefaction=error. -
only
The indexing (recording) is performed by bib2gls (see §9 §??sec:bib2gls + bib2gls: - Managing Reference Databases). Neither \makeglossaries nor - \makenoidxglossaries is permitted. This setting implements - bib2gls: Managing Reference Databases). + Neither \makeglossaries nor \makenoidxglossaries is permitted. + This setting implements undefaction=warn and automatically loads the supplementary -
The glossaries should be displayed using .) + + + +
The glossaries should be displayed using \printunsrtglossary (or \printunsrtglossaries). -
The document build process is (assuming the file is called The document build process is (assuming the file is called myDoc.tex):
- Note that
+ If you want letter groups you will need the --group or -g switch when
+ invoking bib2gls:
+
+
+
+
+ Note that record=only will prevent the The The record=only option will automatically set the
pdflatex myDoc
-
bib2gls myDoc
-
pdflatex myDoc
-
+ pdflatex myDoc
+ bib2gls -g myDoc
+ pdflatex myDoc
+
+
nameref
(New to v1.37 and requires bib2gls v1.8+.) This option is like record=only but additionally records the current label information given by + id="dx1-4095"> but additionally records the current label information given by \@currentlabel and \@currentHref, and provides a more reliable way of @@ -1449,7 +1613,7 @@ class="cmtt-10">\theH⟨counter⟩ for the given location. This option requires hyperref otherwise it will fall back on the usual location records. + id="dx1-4096"> otherwise it will fall back on the usual location records. Remember that \@currentHref is always globally updated whenever \@currentlabel isn’t. This can cause some indexcounter option increments the associated counter every time an entry + id="dx1-4097"> option increments the associated counter every time an entry is indexed, which affects this option. See §9.3.2 Nameref Record for further - details. -
This option is best used with §??sec:recordnameref Nameref + Record for further details. +
This option is best used with counter=chapter or or counter=section if you + id="dx1-4099"> if you want the title included in the location list. If the indexing counter is the default page, only the location number is shown. Similarly for + id="dx1-4100">, only the location number is shown. Similarly for counter=equation (or (or equations=true). + id="dx1-4102">). +
+ alsoindex
Deprecated synonym of hybrid.
alsoindex
This is a hybrid setting that uses bib2gls to fetch entry information from + + + + .bib files, but uses makeindex or xindy to 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 existing + xindy to create the glossary - files. This option should be used with \makeglossaries but not - with its optional argument. This option should not be used with +class="cmtt-10">xindy rule or module is too complicated to convert to a bib2gls rule but + the entries need to be fetched from a bib file. There’s no benefit in using + this option with makeindex. +
+
This option must be used with \makeglossaries but not with its optional + argument. This option should not be used with \makenoidxglossaries. + You may need to change the transcript file used by bib2gls to avoid a + clash with the transcript file used by makeindex or xindy. (This can be + done with bib2gls’s --log-file or -t - option.) -
The glossaries should be displayed using -t option.) +
Each glossary should be displayed using \printglossary (or \printglossaries). This option is expected to be used with bib2gls’s - \printglossaries for all of them). This option is expected to be used + with bib2gls’s sort=none setting and so glossaries-extra-bib2gls is not automatically - - - - loaded. -
The document build process is (assuming the file is called is not + automatically loaded. +
The document build process is (assuming the file is called myDoc.tex):
-pdflatex myDoc -
bib2gls myDoc -
pdflatex myDoc -
makeglossaries myDoc -
pdflatex myDoc -
With the recording on (
+ Note that, in this case, it’s redundant to call bib2gls with the --group
+ or -g switch as makeindex/xindy will insert the group heading
+ information into the corresponding glossary file. (If you want
+ bib2gls to form the letter groups then this hybrid method is
+ inappropriate.)
With the recording on (record=only or , record=alsoindex), any of the commands - that would typically index the entry (such as =nameref or record=hybrid), any of + the commands that would typically index the entry (such as \gls, \glstext or \glsadd) - will add a \glstext or + \glsadd) will add a \glsxtr@record entry to the .aux file. bib2gls can then - read these lines to find out which entries have been used. (Remember - that commands like \glsentryname don’t index, so any use of these - commands won’t add a corresponding \glsxtr@record entry to the - .aux file.) See bib2gls can then + read these lines to find out which entries have been used. (Remember that + commands like \glsentryname don’t index, so any use of these commands + won’t add a corresponding \glsxtr@record entry to the .aux file.) See + §9 §??sec:bib2gls bib2gls: Managing Reference Databases for further details. +
The hybrid method additionally performs the standard indexing action that’s + required for makeindex or xindy to work.
(New to v1.37.) This option will cause the default location counter to automatically switch to equation when inside a numbered equation + id="dx1-4130"> when inside a numbered equation environment, such as equation or or align. The counter can be explicitly overridden + id="dx1-4133">. The counter can be explicitly overridden with counter in the optional arguments of commands like in the optional arguments of commands like \glslink or \gls as usual. -
(New to v1.37.) This option will cause the default location counter to
automatically switch to the corresponding counter when inside a floating
environment, such as figure or or table. The counter can be explicitly overridden
+ id="dx1-4139">. The counter can be explicitly overridden
with counter in the optional arguments of commands like in the optional arguments of commands like \glslink or \gls as
usual. 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 \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
+ \glsfmttext and \glsfmtshort, don’t index. (See §5
+class="tcrm-1000">§??sec:headtitle
Entries in Sectioning Titles, Headers, Captions and Contents). You may
want to consider using \glsadd after the caption (not before). For
-
+ \centering
+ \includegraphics{example-image}
+ \caption{Sample \glsfmttext{foobar} figure}
+ \glsadd{foobar}
+ \end{figure}
+
+
\begin{figure}[htbp]
-
\centering
-
\includegraphics{example-image}
-
\caption{Sample \glsfmttext{foobar} figure}
-
\glsadd{foobar}
-
\end{figure}
-
(New to v1.29.) This option (which doesn’t take a value) is primarily intended for use with bib2gls (v1.4+) and hyperref. It can be used + id="dx1-4144">. It can be used with makeindex or xindy but it will interfere with the number list collation, so you won’t have ranges and you’ll have duplicate page numbers present (but each page number will link to the relevant part of the page @@ -1674,53 +1912,53 @@ href="#glo:numberlist">number list href="#styopt.counter">counter=wrglossary. -
\renewcommand{\glslinkpresetkeys}{% -
\ifmmode \setkeys{glslink}{counter=equation}\fi} -
\renewcommand{\glsaddpresetkeys}{% -
\ifmmode \setkeys{glossadd}{counter=equation}\fi} -
-
By default (with
+
+
By default (with hyperref), the page numbers in ), the page numbers in number lists link back to the top of the relevant page (provided the format uses \glshypernumber). The indexcounter option is designed to link back to the place within the page where + id="dx1-4158"> option is designed to link back to the place within the page where the indexing occurred. It does this by creating a new counter (called wrglossary) + id="dx1-4159">) that’s incremented with \refstepcounter every time an entry is indexed (but not via cross-referencing commands, such as \label is placed class="cmtt-10">\pageref. The location, as seen by the indexing application, is the value of the wrglossary counter but this value is substituted with the page + id="dx1-4160"> counter but this value is substituted with the page reference when number list is typeset. Since the counter is used by all + id="dx1-4161">number list is typeset. Since the counter is used by all entries and is incremented every time any indexing occurs, neither makeindex nor xindy can correctly collate the lists. For example, if the first term to be referenced is indexed three times on page 5 without any intervening terms then the actual locations obtained from wrglossary + id="dx1-4164"> will be 1, 2 and 3, which xindy and makeindex will try to form into the range 1–3, but they should actually all simply appear as page 5, whereas it can actually end up with 5–5. Conversely, a range may not be formed where it would naturally occur if just the page counter was + id="dx1-4167"> counter was used. -
Since Since bib2gls is designed specifically to work with glossaries-extra,
See the See the bib2gls documentation for the save-index-counter resource option
for more details.
@@ -1789,38 +2027,42 @@ class="cmtt-10">save-index-counter
This option governs the use of \newglossaryentry. It was originally a boolean + option, but as from version 1.06, it can now take one of the following values (if + the value is omitted, true is assumed):
\newglossaryentry is not permitted in the is not permitted in the document environment + id="dx1-4177"> environment (default). -
\newglossaryentry behaves as it does in the base glossaries package. That is, where its use is permitted in the document environment, it + id="dx1-4180"> environment, it uses the .glsdefs temporary file to store the entry definitions so that on the next LaTeX run the entries are defined at the beginning of the document environment. This allows the entry information + id="dx1-4182"> environment. This allows the entry information to be referenced in the glossary, even if the glossary occurs before \newglossaryentry. (For example, when the glossary is displayed @@ -1828,31 +2070,32 @@ class="cmtt-10">\newglossaryentry. (For example, when the glossary is dis next LaTeX run has drawbacks that are detailed in the glossaries user manual. -
Remember that if Remember that if \newglossaryentry wouldn’t be allowed in the
document environment with the base environment with the base glossaries package, then it still
won’t be allowed with docdefs=true. If your glossaries occur at the
+ id="dx1-4186">. If your glossaries occur at the
end of the document, consider using docdef=restricted instead.
+ id="dx1-4187"> instead.
(new to version 1.06) \newglossaryentry is permitted in the + id="dx1-4189"> is permitted in the document environment without using the environment without using the .glsdefs file. This means that all entries must be defined before the glossary is displayed, but it avoids the complications associated with saving the entry details @@ -1861,15 +2104,15 @@ class="cmtt-10">.glsdefs file. This means class="cmti-10">key
⟩=⟨value⟩ mechanism (that is, the comma and equal sign) and any makeindex or xindy character that occurs in the sort key or label. If any of those characters + id="dx1-4194"> key or label. If any of those characters are made active in the document, then it can cause problems with the entry definition. This option will allow \newglossaryentry to @@ -1877,52 +2120,77 @@ class="cmtt-10">\newglossaryentry to class="cmtt-10">\makenoidxglossaries, but note that \longnewglossaryentry remains a preamble-only command. -With this option, if an entry appears in the glossary before it has been +
With this option, if an entry appears in the glossary before it has been defined, an error will occur (or a warning if the undefaction=warn + id="dx1-4195"> option 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 the .aux and .gls files).
(new to version 1.34) This option behaves like docdef=restricted but + id="dx1-4197">
but creates the .glsdefs file for atom’s autocomplete support. This file isn’t input by glossaries-extra and so associated problems with the - - - use of this file are avoided, but it allows the autocomplete support to find the labels in the file. As with docdef=restricted, entries may + id="dx1-4198">, 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 options writeglslabels + and writeglslabelnames provided by the base glossaries package. Note + that with these options and docdef=atom, only the entry labels visible + to LaTeX can be saved. So if you are using bib2gls you will only + get the labels of the entries that are selected by bib2gls. +
The The glossaries package allows \newglossaryentry within the document
+ id="dx1-4205">
environment (when used with makeindex or xindy) but the user manual warns
against this usage. By default the prohibits this, only
allowing definitions within the preamble. If you are really determined to define
entries in the document environment, despite all the associated drawbacks, you
+ id="dx1-4209"> environment, despite all the associated drawbacks, you
can restore this with docdef=true. Note that this doesn’t change the
+ id="dx1-4211">. Note that this doesn’t change the
prohibitions that the glossaries package has in certain circumstances (for
example, when using “option 1”). See the glossaries user manual for
href="#styopt.docdef">docdef=restricted. Only use . Only use docdef=true if document definitions
+ id="dx1-4213"> if document definitions
are necessary and one or more of the glossaries occurs in the front
matter.
- This option affects commands that internally use This option affects commands that internally use \newglossaryentry, such as
\newabbreviation, but not the “on-the-fly” commands described in \newabbreviation
This is a boolean option. 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. + + + +
This option has no value and can’t be cancelled. If used, it will automatically
+ create a new glossary with the label abbreviations and redefines
+ \glsxtrabbrvtype to this label. (The file extensions are glg-abr,
+ id="dx1-4216">,
gls-abr and and glo-abr.) In addition, this option defines a shortcut
+ id="dx1-4218">.) In addition, this option defines a shortcut
command
-
+
which is equivalent to
+
which uses \printunsrtglossary.
- The title of the new glossary is given by
- The title of the new glossary is given by
+
- If this command is already defined, it’s left unchanged. Otherwise it’s defined
- to “Abbreviations” if
+ If this command is already defined, it’s left unchanged. Otherwise it’s defined to
+ “Abbreviations” if babel hasn’t been loaded or \acronymname if
- hasn’t been loaded or \acronymname if babel has been loaded. However, if you’re using has
+ been loaded. However, if you’re using babel it’s likely you
- will need to change this. (See it’s likely you will need
+ to change this. (See §14 §??sec:lang Multi-Lingual Support for further
details.)
-
- If the
+ If the abbreviations option is used and the option is used and the acronym option provided by the
+ id="dx1-4229">
- Note that there are no analogous options to the
+
+ Note that there are no analogous options to the glossaries package’s acronymlists
+ id="dx1-4233">
option (or associated commands) as the abbreviation mechanism is handled
differently with glossaries-extra.
This is passed to glossaries but will additionally define
-
+
which is equivalent to If If glossaries-extra-bib2gls is also loaded then this option will additionally
+ id="dx1-4237"> is also loaded then this option will additionally
provide:
-
+
which uses \printunsrtglossary.
+ id="dx1-4239">.
This is passed to glossaries but will additionally define
-
+
which is equivalent to If If glossaries-extra-bib2gls is also loaded then this option will additionally
+ id="dx1-4242"> is also loaded then this option will additionally
provide:
-
+
which uses \printunsrtglossary.
+ id="dx1-4244">.
This is passed to glossaries but if glossaries-extra-bib2gls is
- also loaded then this option will additionally provide:
-
+
which uses \printunsrtglossary.
-
+
This is passed to glossaries but if glossaries-extra-bib2gls is also loaded then this
+ id="dx1-4252"> is also loaded then this
option will additionally provide:
-
+
which uses \printunsrtglossary.
+ id="dx1-4254">.
Unlike the glossaries package option of the same name, this option isn’t boolean
+ but has multiple values: shortcuts=acronyms (or (or shortcuts=acro): set the shortcuts provided
+ id="dx1-4257"> shortcuts=ac: set the shortcuts provided by the : set the shortcuts provided by the glossaries package for
acronyms (such as \ac) but uses the \ac is defined
as \cgls rather than \gls.
-
-
-
- shortcuts=abbreviations (or (or shortcuts=abbr):
- set the abbreviation shortcuts provided by glossaries-extra. (See ): set the abbreviation
+ shortcuts provided by glossaries-extra. (See §4.3
+class="tcrm-1000">§??sec:abbrshortcuts
Shortcut Commands.) These settings don’t switch on the acronym
shortcuts provided by the glossaries package.
- shortcuts=other: set the “other” shortcut commands, but not the shortcut
+ id="dx1-4262">: set the “other” shortcut commands, but not the shortcut
commands for abbreviations or the acronym shortcuts provided by
glossaries. The “other” shortcuts are:
+class="cmss-10">glossaries. The “other” shortcuts are: shortcuts=all (or (or shortcuts=true): implements ): implements shortcuts=ac,
+ id="dx1-4273"> shortcuts=none (or (or shortcuts=false): don’t define any of the shortcut
- commands (default). Note that multiple invocations of the ): don’t define any of the shortcut
+ commands (default). Note that multiple invocations of the shortcuts option option within the same option
list will override each other. After the After the glossaries-extra package has been loaded, you can set available options
using
-
+
The abbreviations and and docdef options may only be used in the preamble. Additionally,
+ id="dx1-4281"> options may only be used in the preamble. Additionally,
docdef can’t be used after can’t be used after \makenoidxglossaries.
+ id="dx1-4283">.
The The glossaries package provides \nopostdesc which may be used in the descriptionglossaries-extra
+
which has a similar function but only suppresses the post-description punctuation. It
doesn’t suppress the use of \glsxtrpostdescription which allows the use of
@@ -2446,19 +2742,20 @@ class="cmtt-10">\glsxtrpostdescription not before.) The
post-description hook can counter-act the effect of \glsxtrnopostpunc
using
-
+
These commands have no effect outside of the glossary (except with standalone
entries that use \glsxtractivatenopost and \glspostdescription, see \glspostdescription, see
+§10.4
-§??sec:glossentry Standalone Entry Items).
- The commands used by The commands used by glossaries to automatically produce an error if an entry is
undefined (such as \glsdoifexistsundefaction option into
account.
- The The \newglossaryentry command has three new keys: category, which sets the category label for the given entry. By default this
is general. See §6 Categories for further information about categories.
- alias, which allows an entry to be alias to another entry. See §10.5 Entry
- Aliases for further details.
- seealso, which performs much like see, but allows for separate “see” and
- “see also” treatment. See §2.3 Cross-References (“see” and “see also”) for
- further details. This apply to all entry defining commands (such as §??sec:see Cross-References (“see” and “see
+ also”) for further details. This apply to all entry defining commands (such as \newabbreviation).
- The test file The test file example-glossaries-xr.tex contains dummy entries with a
mixture of seeexample-glossaries-*.tex The The \longnewglossaryentry command now has a starred version (as from v1.12)
that doesn’t automatically insert
at the end of the description field.
- at the end of the description field.
+
+
The descriptionplural key is left unset unless explicitly set in ⟨options⟩.
- The unstarred version no longer hard-codes the above code (which removes
+ The unstarred version no longer hard-codes the above code (which removes
trailing space and suppresses the post-description hook) but instead uses:
-
+
This can be redefined to allow the post-description hook to work but retain the
\unskip part if required. For example:
@@ -2556,12 +2860,12 @@ class="cmtt-10">\unskip part if required. For example:
This will discarded unwanted trailing space at the end of the description but won’t
+
+ This will discarded unwanted trailing space at the end of the description but won’t
suppress the post-description hook.
- The unstarred version also alters the base The unstarred version also alters the base glossaries package’s treatment of the
2.1
- Note that this modified unstarred version doesn’t append Note that this modified unstarred version doesn’t append \glsxtrpostlongdescription
to the description’s plural form.
- The The \newterm command (defined through the index. The \newacronym command is modified
-to use the new abbreviation interface provided by The The \makeglossaries command now has an optional argument.
-
+
If ⟨list⟩ is empty, \makeglossaries behaves as per its original definition in the
@@ -2615,36 +2920,36 @@ class="cmtt-10">\makeglossaries behaves as per its original definition in
class="cmss-10">glossaries package, otherwise ⟨list⟩ can be a comma-separated list of glossaries that
need processing with an external indexing application.
- This command is not permitted with the This command is not permitted with the record=only package option. Without
-the optional argument, it’s permitted with record=alsoindex. With the optional
-argument, it’s only permitted with the default =hybrid. With the optional argument,
+it’s only permitted with the default record=off.
- It should then be possible to use It should then be possible to use \printglossary for those glossaries listed in ⟨list⟩
and \printnoidxglossary for the other glossaries. (See the accompanying file
sample-mixedsort.tex for an example.)
-
- You will need at least version 2.20 of
+ You will need at least version 2.20 of makeglossaries or at least version 1.3 of
@@ -2662,25 +2967,25 @@ href="#styopt.automake">automake
+
As from version 1.31, there is a new command like As from version 1.31, there is a new command like \glsadd where the mandatory
argument is a comma-separated list of labels:
-
+
This simply iterates over ⟨list⟩ and does \glsadd[⟨]{⟨label⟩} for each entry in the
list.
- As from version 1.37, you can make commands like As from version 1.37, you can make commands like \gls or \glslink
automatically use } in the optional argument of the corresponding
\gls, \glslink etc).
-
+
The optional argument ⟨label⟩ defaults to \glslabel and indicates the label to use in
@@ -2726,61 +3031,63 @@ class="cmtt-10">format={⟨format⟩} prepended to the
list.
- For example, with:
+ For example, with:
then
+ then \gls[format=hyperbf]{sample} will be equivalent to
Note that the explicit range markers will prevent a match unless you include
+
+ Note that the explicit range markers will prevent a match unless you include
them in ⟨format list⟩ (in which case, be sure to add both the start and end
formats).
- Here’s another example:
+ Here’s another example:
In this case
+ In this case \gls[format=hyperbf]{sample} will now be equivalent to:
-
+
- The
+ The glossaries-extra package provides extra keys for commands like \gls and
\glstext:
This is a boolean key. If true, this suppresses the indexing. (That is, it
+ prevents \gls or whatever from adding a line to the external glossary
file.) This is more useful than the first use might not be the most pertinent use. (If you
want to apply indexonlyfirst to selected entries, rather than all of them, you
- can use the to selected entries, rather than all of them,
+ you can use the indexonlyfirst attribute, see §6 Categories for further details.)
- Note that the §??sec:categories Categories
+ for further details.) Note that the noindex key isn’t available for \glsadd (and
+ (and \glsaddall)
- since the whole purpose of that command is to index an entry.
- (New to v1.14.) This is may only take the values before or after. By
- default, commands that both index and display link text (such as \gls,
- \glstext and \glslink), perform the indexing before the link text as the
- indexing creates a whatsit that can cause problems if it occurs after the
- link text. However, it may be that in some cases (such as long phrases) you
- may actually want the indexing performed after the link text. In this case
- you can use wrgloss=after for specific instances. Note that this option
- doesn’t have an effect if the indexing has been suppressed through other
- settings (such as after. By default,
+ commands that both index and display link text (such as \gls, \glstext
+ and \glslink), perform the indexing before the link text as the indexing
+ creates a whatsit that can cause problems if it occurs after the link text.
+ However, it may be that in some cases (such as long phrases) you may
+ actually want the indexing performed after the link text. In this case you
+ can use wrgloss=after for specific instances. Note that this option doesn’t
+ have an effect if the indexing has been suppressed through other settings
+ (such as noindex).
- The default value is set up using
- The default value is set up using
+
+
which is defined as:
This sets the conditional
- This sets the conditional
+
+
which is used to determine where to perform the indexing.
- This means you can set the This means you can set the wrgloss attribute to \GlsXtrSetDefaultGlsOpts\glsxtrinitwrgloss (New to v1.21.) This is a boolean key. The default is hyperoutside=true,
which puts the hyperlink outside \glstextformat, so that commands like \gls
- will effectively do will set
+ will set hyperoutside=false for all entries that are assigned to the category
mathrelation and
@@ -2936,10 +3252,10 @@ class="cmtt-10">mathrelation will use
+ will use \mathrel instead of \glstextformat resulting in: This key must have a control sequence name as its value. The command formed
+ from this name must exist and must take one argument. (Use relax for
+ default behaviour.) If set, this overrides the textformat
- attribute and attribute and
+ \glstextformat. See the soul example in §2.6 §??sec:glsunset First Use
Flag.
- Locally redefines \glolinkprefix to the given value. It should match the
prefix for the desired glossary.
- Explicitly set the location to this value (see below).
+ Set the corresponding hyperlink location (see below).
+ You can set the default options used by You can set the default options used by \glslink, \gls etc with:
-
+
For example, if you mostly don’t want to index entries then you can do:
and then use, for example,
+ and then use, for example, \gls[noindex=false]{sample} when you actually want
the location added to the \glslink Note that if you don’t want Note that if you don’t want any indexing, just omit \makeglossaries and
wrgloss\glsxtrinitwrgloss
- If you want to change the default value of
+ If you want to change the default value of format, you can instead use:
-
+
This has the advantage of also working for \glsadd. For example, if you
want all locations in the back matter to appear in italic (unless explicitly
@@ -3055,12 +3381,12 @@ overridden):
- Commands like
+
+ Commands like \gls have star (*) and plus (hyper=false and hyper=true. The glossaries-extra package provides a way to add a
third modifier, if required, using
-
+
where ⟨char⟩ is the character used as the modifier and ⟨options⟩ is the default set of
options (which may be overridden). Note that ⟨char⟩ must be a single character (not a
UTF-8 character, unless you are using XƎLATEX or LuaLATEX).
-
- Example:
+
+ Example:
This means that
+ This means that \gls!{sample} will be equivalent to \gls[noindex]{sample}. It’s
not possible to mix modifiers. For example, if you want to do
@@ -3104,51 +3430,51 @@ not possible to mix modifiers. For example, if you want to do
you can use
+ you can use \gls*[noindex]{sample} or \gls![hyper=false]{sample} but you
can’t combine the * and ! modifiers.
- There is a new hook that’s used each time indexing information is written to the
+ There is a new hook that’s used each time indexing information is written to the
external glossary files:
-
+
where ⟨label⟩ is the entry’s label. This does nothing by default but may be redefined.
(See, for example, the accompanying sample file sample-indexhook.tex, which uses
this hook to determine which entries haven’t been indexed.)
- There’s also a new hook (from v1.26) that’s used immediately before the options
+ There’s also a new hook (from v1.26) that’s used immediately before the options
are set by the \gls-like and \glstext-like commands:
-
+
(The base package provides \glslinkpostsetkeys that’s used immediately after the
options are set.)
- As from version 1.30 there are also similar hooks for As from version 1.30 there are also similar hooks for \glsadd:
-
+
and
-
+
For example, to default to using the equation counter in maths mode:
@@ -3156,13 +3482,13 @@ class="cmss-10">equation
- In this case, the counter can be overridden with an explicit use of
+ In this case, the counter can be overridden with an explicit use of counter in the
optional argument of equations Alternatively, to enforce this (overriding the option argument):
+ Alternatively, to enforce this (overriding the option argument):
- As from version 1.14, there are two new keys for
+
+ As from version 1.14, there are two new keys for \glsadd: thevalue and thevalue keys is intended
primarily for adding locations in supplementary material that can’t be obtained from
a counter.
- The principle key The principle key thevalue is for the location value. The other key theHvalueprefix
- For example,
+ For example, makeindex will only accept locations in the form [⟨num⟩⟨
- This location value will be accepted by
+ This location value will be accepted by bib2gls, since it will allow any location and
@@ -3256,24 +3582,24 @@ class="cmss-10">format For example, suppose the file For example, suppose the file suppl.tex contains:
This has an entry on page S.2. Suppose another document wants to include this
+\usepackage{glossaries-extra}
+\newglossaryentry{sample}{name={sample},description={an example}}
+\renewcommand{\thepage}{S.\arabic{page}}
+\begin{document}
+First page.
+\newpage
+\gls{sample}.
+\end{document}
+
+ This has an entry on page S.2. Suppose another document wants to include this
location in the glossary. Then this can be done by setting thevalue to
- This location value will be accepted by
+ This location value will be accepted by makeindex as it’s in the form ⟨num⟩⟨sep⟩⟨num⟩.
- If you want hyperlinks, things are more complicated. First you need to set the
+ If you want hyperlinks, things are more complicated. First you need to set the
externallocationexternallocation Next you need to add
+ Next you need to add glsxtrsupphypernumber as the format:
Both documents will need to use the
+ Both documents will need to use the hyperref package. Remember that the counter
used for the location also needs to match. If sample-suppl-main-hyp.tex for an example that uses
hyperref.
-
- For example, if both
+ For example, if both sample-suppl-hyp.pdf and sample-suppl-main-hyp.pdf
are in the same directory, then viewing sample-suppl-main-hyp.pdf in Evince will
take you to the correct location in the linked document (when you click on the S.2
external link), but Okular will take you to the top of the first page of the linked
document.
- This method can only be used where there is one external source for the
+ This method can only be used where there is one external source for the
designated category (identified by the externallocation.aux
+
The value of the The value of the see key is now saved as a field. This isn’t the case with glossaries,
-where the key is now saved as a field. This isn’t the case with
+glossaries, where the see value is simply used to directly write a line to the corresponding
-glossary file and is then discarded. This is why the value is simply used to directly write a line to the
+corresponding glossary file and is then discarded. This is why the see key can’t be used
-before key
+can’t be used before \makeglossaries (since the file hasn’t been opened yet). It’s also the
-reason why the see key doesn’t have any effect when used in entries that
-are defined in the document environment. Since the value isn’t saved, it’s
-not available when the .glsdefs file is created at the end of the document
-and so isn’t available at the start of the document environment on the next
-run.
- This modification allows (since the file hasn’t been opened
+yet).
+ This modification allows glossaries-extra to provide
-
+
which is used at the end of the document to automatically add any unused
cross-references unless the package option indexcrossrefs was set to false.
- As a by-product of this enhancement, the was set to false.
+
+
+
+ Note that even though the see key will now work for entries
-defined in the key will now work for entries defined in the
+document environment, but it’s still best to define entries in the
-preamble, and the environment, it’s still best to define entries in the preamble, and
+the see key still can’t perform any indexing before the file has been
-opened by key still can’t perform any indexing before the file has been opened
+by \makeglossaries. Note that glossaries v4.24 introduced the seenoindex
+ id="dx1-8011">
package option, which can be used to suppress the error when the see key
+ id="dx1-8012"> key
is used before \makeglossaries, so seenoindex=ignore will allow the will allow the see
+ id="dx1-8014">
value to be stored even though it may not be possible to index it at that
point.
- As from version 1.06, you can display the cross-referenced information for a given
+ As from version 1.06, you can display the cross-referenced information for a given
entry using
-
+
This internally uses
-
+
where ⟨tag⟩ and ⟨xr list⟩ are obtained from the value of the entry’s see field (if
+ id="dx1-8017"> field (if
non-empty). By default, this just does \glsseeformat[⟨tag⟩xr list⟩}{},
which is how the cross-reference is displayed in the number list. Note that
\glsxtrusesee does nothing if the see field hasn’t been set for the entry given by
+ id="dx1-8019"> field hasn’t been set for the entry given by
⟨label⟩.
- As with the base As with the base glossaries package, package, \glsseeformat is defined to do \emph{⟨tag⟩xr list⟩}. The third argument is always ignored and is present for
makeindex, which always requires a final argument to encapsulate the associated
+ id="dx1-8021">, which always requires a final argument to encapsulate the associated
location. The command
-
+
used to iterate over the list of cross-reference labels is also unchanged from
the base glossaries package, with each item in the list formatted according
+ id="dx1-8023"> package, with each item in the list formatted according
to:
-
+
This is defined by the glossaries package to:
- The
+
+ The glossaries package provides
-
+
to format items in a cross-reference list (identified with the see key or key or \glssee). This
was originally defined to use \glsentryname{⟨} since it makes more sense for the
cross-reference to match the way the term appears in the glossary. Unfortunately this
caused a problem when the name field was sanitized, which used to be the default
+ id="dx1-8033"> field was sanitized, which used to be the default
setting, so glossaries v3.0 changed the default definition of this command to
use \glsentrytext instead. Since the name and and text field are quite often
+ id="dx1-8035"> field are quite often
the same, this change usually doesn’t have a noticeable effect. However,
now that the name field is no longer sanitized (following the redesign of
+ id="dx1-8036"> field is no longer sanitized (following the redesign of
glossaries v4.0) it makes more sense to restore this command to its original
behaviour, but to take account of abbreviations
- (Note that as from
+ (Note that as from glossaries-extra version 1.42, this now uses \glsfmttext and
\glsfmtname instead of just referencing the text and and name fields. This helps to ensure
+ id="dx1-8038"> fields. This helps to ensure
that any formatting is correctly applied.)
- If you want to restore the If you want to restore the glossaries v3.0+ definition just do:
- The
+
+ The glossaries-extra package provides package provides \glsxtrhiername and its case-changing
+ id="dx1-8040"> and its case-changing
variants that may be used within the definition of \glsseeitemformat if required.
These display the hierarchy for sub-entries rather than just the name, which may be
more helpful in cross-references.
-
+
performs a recursive action:
If the entry given by ⟨label⟩ has a parent, then \glsxtrhiername{⟨parent
@@ -3650,84 +3963,85 @@ class="cmti-10">parent If the entry given by ⟨label⟩ is an abbreviation (that is, it has the short field
+ id="dx1-8046"> field
set) then the short form is displayed (using \glsfmtshort) otherwise the
name is displayed (using \glsfmtname). The first step above is skipped if the entry doesn’t have a parent. Each level is separated
+class="cmtt-10">\glsfmtname). The first step above is skipped if the entry doesn’t have a parent. Each level is separated
by:
-
+
which defaults to “ ⊳ ”. This can be redefined as appropriate.
- There are some case-changing variants:
- There are some case-changing variants:
+
+
The top-level has the first letter changed to upper case (either \Glsfmtshort or
\Glsfmtname). There’s no case-change for sub-entries.
-
+
All levels have the first letter changed to upper case (either \Glsfmtshort or
\Glsfmtname).
-
+
The top-level is converted to upper case (either \GLSfmtshort or \GLSfmtname).
There’s no case-change for sub-entries.
-
+
All levels are converted to upper case (either \GLSfmtshort or \GLSfmtname).
-
-
-
- Suppose you want to suppress the number list using Suppose you want to suppress the number list using nonumberlist. This
+ id="dx1-8053"> Another approach in this situation is to use the post description hook
+ Another approach in this situation is to use the post description hook
with \glsxtrusesee to append the cross-reference after the description. For
example:
@@ -3735,22 +4049,22 @@ example:
Now the cross-references can appear even though the
+ Now the cross-references can appear even though the number list has been
suppressed.
- As from v1.16, there’s a separate You can display the formatted list of cross-references stored in the You can display the formatted list of cross-references stored in the seealso key
+ id="dx1-8062"> key
using:
-
+
This works in much the same way as \glsxtrusesee but it internally uses
-
+
For example:
- The
+
+ The alias key only contains a single label not a list, but if you want to ensure
+ id="dx1-8065"> key only contains a single label not a list, but if you want to ensure
consistent formatting with \glsxtrusesee and \glsxtruseseealso you can use
(from v1.42):
-
- The actual unformatted comma-separated list ⟨
+ The actual unformatted comma-separated list ⟨xr-list⟩ stored in the seealso field
+ id="dx1-8067"> field
can be accessed with:
-
+
This will just expand to the ⟨xr-labels⟩ provided in the value of the seealso key. There’s
+ id="dx1-8069"> key. There’s
no corresponding command to access the see field. If you really need to access it, you
+ id="dx1-8070"> field. If you really need to access it, you
can use commands like \glsxtrfielduse, but remember that it may start with
[⟨tag⟩], so it can’t be automatically treated as a simple comma-separated
list.
- As mentioned above, the base As mentioned above, the base glossaries package provides \glsseelist, which
+ id="dx1-8071">, which
requires a comma-separated list of labels as the argument. The argument isn’t fully
expanded, so it’s not suitable to use, for example, \glsxtrseealsolabels{⟨label⟩} as
the argument. For convenience, glossaries-extra provides
-
+
which fully expands its argument and passes it to \glsseelist.
- The The seealso key implements the automatic indexing using
-
+
which just does The command that produces this “see also” text is
- The command that produces this “see also” text is
+
+
If \alsoname (provided by language packages) is defined then (provided by language packages) is defined then \seealsoname will
simply be defined to \alsoname otherwise it will be defined to see also.
- The language-sensitive The language-sensitive \alsoname is used by general indexing packages, such as
makeidx, so if you redefine , so if you redefine \alsoname the change will apply to normal indexes as well
as glossaries. If you only want to change the text produced by the seealso key
+ id="dx1-8080"> key
without affecting general indexing (with \index) then redefine \seealsoname
instead.
-
+
Recall from the Recall from the glossaries package that commands such as \gls display text at
that point in the document (optionally with a hyperlink to the relevant
@@ -3930,7 +4244,7 @@ whether or not it actually has a hyperlink. The actual text and the way
it’s displayed depends on the command used (such as \gls) and the entry
format.
- The default entry format ( The default entry format (\glsentryfmt) used in the link-text by commands like
@@ -3953,35 +4267,39 @@ class="cmss-10">glossaries-extra If an entry is assigned to a category that has the regular attribute set (see attribute set
+ (see §6
- Categories), the entry is considered a regular entry, even if it has a value
- for the §??sec:categories An entry that doesn’t have a value for the short key is assumed to
be a regular entry, even if the regular If an entry does has a value for the short key and hasn’t been marked
+ as a regular entry through the regular attribute, it’s not considered
+ a regular entry. In this case \glsentryfmt uses \glsxtrgenabbrvfmt (defined by
- glossaries-extra) which is governed by the abbreviation style (see
+ (defined by glossaries-extra) which is governed by the abbreviation style
+ (see §4.2
- §??sec:abbrstyle Abbreviation Styles).
+ This means that entries with a short form can be treated as regular entries rather
+ This means that entries with a short form can be treated as regular entries rather
than abbreviations if it’s more appropriate for the desired style.
- As from version 1.04, As from version 1.04, \glsentryfmt now puts \glsgenentry in the argument of
the new command
-
+
This just does its argument ⟨text⟩ by default. This means that if you want regular
entries in a different font but don’t want that font to apply to abbreviations, then
@@ -4041,60 +4362,60 @@ overridden by the textformat attribute.
- For example:
+ For example:
You can access the label through
+ You can access the label through \glslabel. For example, you can query the
category:
or query the category attribute, for example, provide a custom attribute called
+ \glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}}
+
+ or query the category attribute, for example, provide a custom attribute called
font:
As from version 1.21, it’s simpler to just do, for example:
+\renewcommand*{\glsxtrregularfont}[1]{%
+ \glsifattribute{\glslabel}{font}{sf}{\textsf{#1}}{#1}}
+
+ As from version 1.21, it’s simpler to just do, for example:
without redefining
+ without redefining \glsxtrregularfont.
- As from version 1.30, there is also a command for abbreviations that encapsulates
+ As from version 1.30, there is also a command for abbreviations that encapsulates
\glsxtrgenabbrvfmt:
-
+
This also just does its argument by default. Font changes made by abbreviation styles
are within ⟨text⟩.
- The The \glspostlinkhook provided by the glossaries package to insert information
after the link-text produced by commands like \gls and \glstext is redefined
to
-
+
This command will discard a following full stop (period) if the discardperiod attribute
is set to “true” for the current entry’s category. It will also do
-
+
if a full stop hasn’t be discarded and
-
+
if a full stop has been discarded.
- It may be that you want to check some other setting (rather than a category
+ It may be that you want to check some other setting (rather than a category
attribute) to determine whether or not to discard a following full stop. In which case
you can redefine:
-
+
You can access the field’s label using \glslabel. This command should do ⟨true⟩ if the
@@ -4143,12 +4464,12 @@ definition is simply:
which means that no additional checks are performed. (Only the recognised category
+
+ which means that no additional checks are performed. (Only the recognised category
attributes will be checked.)
-
- By default
+ By default \glsxtrpostlink just does \glsxtrpostlink⟨category⟩general You can define the post-link hook command using You can define the post-link hook command using \newcommand, for
example:
or, as from v1.31, you can use
- or, as from v1.31, you can use
+
+
This is simply a shortcut for: The sentence-ending hook is slightly more complicated. If the command
+ The sentence-ending hook is slightly more complicated. If the command
\glsxtrpostlink⟨category⟩ There are some convenient commands you might want to use when customizing
+ There are some convenient commands you might want to use when customizing
the post-link-text category hooks:
-
-
-
-
\renewcommand*{\acronymtype}{main}
-
-
-
-
-
-
-
-
-2. Modifications to Existing Commands and Styles
-2.1 Defining Entries
-
-
-
-
\leavevmode\unskip\nopostdesc
-
-
-
\renewcommand*{\glsxtrpostlongdescription}{\leavevmode\unskip}
-
-2.2 Entry Indexing
-
-
-
\GlsXtrAutoAddOnFormat{hyperbf}{counter=chapter}
-
\glsadd[format=hyperbf,counter=chapter]{sample}\gls[format=hyperbf]{sample}
-
\GlsXtrAutoAddOnFormat[dual.\glslabel]{hyperbf}{}
-
\glsadd[format=hyperbf]{dual.sample}\gls[format=hyperbf]{sample}
-
-
\newcommand*{\glsxtrinitwrgloss}{%
-
\glsifattribute{\glslabel}{wrgloss}{after}%
-
{%
-
\glsxtrinitwrglossbeforefalse
-
}%
-
{%
-
\glsxtrinitwrglossbeforetrue
-
}%
-
}
-
-
\glssetcategoryattribute{mathrelation}{hyperoutside}{false}
-
\glssetcategoryattribute{mathrelation}{textformat}{mathrel}
-
-
\GlsXtrSetDefaultGlsOpts{noindex}
-
-
\backmatter
-
\GlsXtrSetDefaultNumberFormat{hyperit}
-
-
\GlsXtrSetAltModifier{!}{noindex}
-
\gls[noindex,hyper=false]{sample}
-
-
-
-
-
\renewcommand{\glslinkpresetkeys}{%
-
\ifmmode \setkeys{glslink}{counter=equation}\fi}
-
\renewcommand{\glsaddpresetkeys}{%
-
\ifmmode \setkeys{glossadd}{counter=equation}\fi}
-
\renewcommand{\glslinkpostsetkeys}{%
-
\ifmmode \setkeys{glslink}{counter=equation}\fi}
-
\renewcommand{\glsaddpostsetkeys}{%
-
\ifmmode \setkeys{glossadd}{counter=equation}\fi}
-
\glsadd[thevalue={Supplementary Material}]{sample}
-
\documentclass{article}
-
\usepackage{glossaries-extra}
-
\newglossaryentry{sample}{name={sample},description={an example}}
-
\renewcommand{\thepage}{S.\arabic{page}}
-
\begin{document}
-
First page.
-
\newpage
-
\gls{sample}.
-
\end{document}
-
\documentclass{article}
-
\usepackage{glossaries-extra}
-
\makeglossaries
-
\newglossaryentry{sample}{name={sample},description={an example}}
-
\begin{document}
-
Some \gls{sample} text.
-
\printglossaries
-
\glsadd[thevalue={S.2}]{sample}
-
\end{document}
-
\glssetcategoryattribute{supplemental}{externallocation}{suppl.pdf}
-
\newglossaryentry{sample}{category=supplemental,
-
name={sample},description={an example}}
-
\glsadd[thevalue={S.2},format=glsxtrsupphypernumber]{sample}
-
2.3 Cross-References (“see” and “see also”)
-
-
-
-
-
-
-
-
-
\renewcommand*{\glsseeitemformat}[1]{\glsxtrhiername{#1}}
-
-
\renewcommand*{\glsseeitemformat}[1]{%
-
\ifglshasshort{\glslabel}{\glsfmttext{#1}}{\glsfmtname{#1}}%
-
}
-
\renewcommand*{\glsseeitemformat}[1]{\glsentrytext{#1}}
-
-
-
⟩} is done followed by \glsxtrhiernamesep then:
-
-
-
-
-
-
-
\renewcommand*{\glsxtrpostdescgeneral}{%
-
\ifglshasfield{see}{\glscurrententrylabel}
-
{, \glsxtrusesee{\glscurrententrylabel}}%
-
{}%
-
}
-
-
-
\renewcommand*{\glsxtrpostdescgeneral}{%
-
\ifglshasfield{see}{\glscurrententrylabel}
-
{, \glsxtrusesee{\glscurrententrylabel}}%
-
{}%
-
\ifglshasfield{seealso}{\glscurrententrylabel}
-
{ (\glsxtruseseealso{\glscurrententrylabel})}%
-
{}%
-
}
-
-
-
-
-
-2.4 Entry Display Style Modifications
-
-
-
\renewcommand*{\glsxtrregularfont}[1]{\textsf{#1}}
-
\renewcommand*{\glsxtrregularfont}[1]{%
-
\glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}}
-
\glssetcategoryattribute{general}{font}{sf}
-
\renewcommand*{\glsxtrregularfont}[1]{%
-
\glsifattribute{\glslabel}{font}{sf}{\textsf{#1}}{#1}}
-
\glssetcategoryattribute{general}{textformat}{textsf}
-
-
-
-
-
-
\newcommand*{\glsxtrifcustomdiscardperiod}[2]{#2}
-
\newcommand*{\glsxtrpostlinkgeneral}{%
-
\glsxtrpostlinkAddDescOnFirstUse
-
}
-
-